SC33-0037-1 

File No. S360/S370-29 



Program Product 



OS 

PL/I Optimizing Compiler: 

CMS User's Guide 



Program Numbers 5734-PL1 
5734-LM4 
5734-LM5 

(These program products are available 
as composite package 5734-PL3) 





JL 


°)r 




Second Edition (June 1973) 

This is a major revision of and obsoletes SC33-0037-0. This edition 
applies to Version 1 Release 2 Modification of the optimizing compiler 
and to all subsequent releases until otherwise indicated in new editions 
or Technical Newsletters. Information has been included on the 
facilities that have been introduced with release 2 of the compiler,, and 
on the alterations that have been made to improve PL/I under CMS. 

A number of changes have been made to the compiler options. 

The COUNT option has been introduced. This results in code being 
generated that will produce a count of the number of times each 
statement has been executed during a program. 

The INCLUDE option has been introduced. This allows secondary text 
to be included without the overhead of using the complete 
preprocessor facility. 

The MARGINS and SEQUENCE options have been altered so that two 
default values are set up when the compiler is installed. One value 
is for F-format records and one for V or U-format records. This 
simplifies the compilation of source programs with V-format records. 

A NOSEQUENCE option has been introduced. 

All these changes are described in chapter 3. 

Changes have also been made in the execution time options. A method has 
been introduced whereby they can be specified within the PL/I program. 
COUNT and NOCOUNT and FLOW and NOFLOW have alos been introduced as 
execution time options, giving the programmer control of whether COUNT 
or FLOW output is generated for a particular run of a program. These 
changes are described in chapter 4. 

Changes have also been made in the conventions that apply when passing 
parameters to the main PL/I procedure. These are described in chapter 
2. Improved messages which are generated when an attempt is made to use 
a PL/I facility that is not available under CMS are also listed in this 
chapter. 

Additionally two new sections have been added in chapter 1. The first 
describes the action required if you wish to write source statements to 
be included as secondary input text to your PL/I program. The second 
describes the action required if you wish to produce compiled modules 
that can be included in a text library. A number of minor alterations 
and corrections have also been made throughout the book. Changes are 
marked with a vertical line to the left of the change. 

Changes are continually being made to the information herein; before 
using this publication in connection with the operation of IBM systems,, 
consult the latest IBM system/360 Bibliography SRL newsletter. Order No. 
GN20-0360, for the editions that are applicable and current. 

Changes are continually being made to the information herein; before 
using this publication in connection with the operation of IBM systems, 
consult the latest IBM System/360 and System/370 Bibliography, Order 
No. GA22-6822, and associated Technical Newsletters for the editions 
that are applicable and current. 

Requests for copies of IBM publications should be made to your IBM 
representative or to the IBM branch office serving your locality. 

A form for reader" s comments is provided at the back of this 
publication. If the form has been removed,, comments may be addressed to 
IBM United Kingdom Laboratories Ltd., Programming Publications, Hursley 
Park, Winchester, Hampshire. England. 

© Copyright International Business Machines Corporation 1973 



Preface 



This manual explains, for the users of the Conversational Monitor System 
(CMS) component of the IBM Virtual Machine Facility/37 f how to invoke 
the PL/I Optimizing Compiler and use its conversational I/O 
capabilities. 

The reader is assumed to have a basic knowledge of PL/I and of CMS. 

Chapter 1 is an introduction to PL/I under CMS. It aims to give enough 
information to allow the reader to enter, compile, and execute a 
straightforward PL/I program under CMS. It also aims to act as a guide 
to further sources of information and to provide enough background 
material to allow the reader to make full use of the potentialities of 
the optimizing compiler under CMS. 

Chapter 2 is the reference source for the special restrictions and 
conventions that apply to PL/I when it is compiled by the optimizing 
compiler and executed under CMS. 

Chapter 3 is the reference source for the PLIOPT command and its 
options. 

Chapter 4 is the reference source for the execution time options that 
are available when executing programs compiled by the PL/I Optimizing 
Compiler. 

Figure P. 1 is a guide to using this book. 
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in an executable form by use 
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to create a MODULE file 



LOGOUT command 



Ends the terminal 
session 



END 



Figure 1.1. The steps involved in entering and executing a PL/I 
program under CMS 



Chapter 1: Writing and Running a PL/I Program Under 
CMS 



Introduction 

Executing a PL/I program under CMS is a very simple process. You will 
need to carry out the following six steps using CMS commands at a 
terminal. 

1. LOGIN at the terminal. 

2. IPL CMS. 

3. Write or alter a source program using the CMS editor. 

4. Compile the source program using the PLIOPT command. 

5. Execute the compiled program using the GLOBAL coirirand to access the 
PL/I libraries followed by the LOAD and START commands. Or create 
a MODULE file using the GLOBAL, LOAD, and GENMOD commands for 
subsequent execution without further use of the LOAD command. 

6. End the session. 

The remainder of this chapter leads you through the steps listed above 
one by one. A standard approach has been adopted for each step. The 
format is : 

1. Summary and_,example . These give you the essential information to 
run straightforward programs and list any special cases that 
require additional action. These are the only sections you will 
need to look at during your first CMS sessions. 

2. B§,ckgyQ^Ijd_inf u ormation. This amplifies the information in the 
summary and is intended to enable the user to get the best possible 
results from using PL/I under CMS. 

3. Special_considerations . This explains what to do in the special 
cases listed in the summary. Special cases have been kept separate 
to prevent them making a simple process appear complex. This 
section is omitted where there are no special cases. 

4. Sources of further information. This lists the manuals that you 
will require for any further information you may need. 

A sample terminal session can be folded out from the end of the book. 
This shows all, seven steps involved on one page and can be used for 
quick reference. 

Other chapters in this book are for reference. Chapter 2 lists the 
special restrictions and conventions that apply to PL/I that is compiled 
by the optimizing compiler and executed under CMS. Chapter 3 lists the 
options and syntax of the PLIOPT command. Chapter 4 lists the execution 
time options that are available for programs compiled by the optimizing 
compiler. 

\ System requirements: The PL/I Optimizing Compiler requires a minimum of 
J320K bytes of virtual storage for the CMS virtual machine. This figure 
|is the same as the suggested minimum for CMS. 

The next page shows you how to start a CMS session. 
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Starting the Session-The LOGIN Command 



SUMMARY 



To start a terminal session, you switch on the terminal and enter the 
LOGIN command, specifying the identifier of your virtual machine. The 
terminal responds by requesting your password if one is required by your 
installation. After you have entered the password, the system responds 
with a log message. You are now in the control program environment of 
VM/370, and can invoke CMS. 



Example of use of the LOGIN, .Command 



EXAMPLE OF LOGIN 



Terminal Printout 



Notes and comments 



(you switch on the terminal) 

VM/370 ONLINE Message shows a virtual machine 

(you may have to press attention is available, 
key to unlock the terminal keyboard.) 



login skylark 



ENTER PASSWORD: 
(password entered here) 



LOGIN command followed by 
identifier for your virtual 
machine. 

System requests password. 

You enter password. The printing 

of the password will normally be 

suppressed or overprinted for 

security. 



LOGMSG - 09:12:09 04/02/72 Log message showing time and 

RUNNING SYS010 - COLD START AT 09:00 date of message, system identi- 

LOGIN AT 09:13:04 THURSDAY 04/02/72 fication and start time, time 

| and date of signing on. 



Con ven tions : 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes. 

3. system response is in upper case (capital) letters; programmer 
input in lower case. 



BACKGROUND 



CP and Your Virtual Machine 



When you have keyed in your LOGIN command and your password, you are in 
control of a virtual machine. Your terminal can be considered as the 



10 



console of your virtual machine. You can thus carry out many of the 
operations of the operator of the real machine. This includes the 
ability to invoke a number of operating systems, among them CMS. 

Your virtual machine is controlled in the real machine by a control 
program known as Control Program/370 (CP/370) . When you have received 
the log message, you are in control of your virtual machine and said to 
be in the "CP environment". 



SOURCES OF FURTHER INFORMATION 

Topic Reference Source 

LOGIN command VM/370 Command Language User's Guide 

LOGMSG meaning VM/370 Terminal User's Guide 
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Invoking CMS-The IPL Command 

SUMMARY 

To invoke CMS, you issue the IPL (initial Program Load) command. 

Examp le of use of .the ,„IPL .command 

r — . . -_- - 

EXAMPLE OF IPL 

Terminal Printout Notes and comments 

ipl cms The IPL CMS command. 

I 

CMS 1.0 PLC 5 WEDNESDAY 04/07/72 09.13.50 

I 

| Message confirms CMS is invoked and 

I that CMS commands may be entered. 



Con ve nt ions : 

1. A carriage return is assumed after all programmer input. 

2. system response is in upper case (capital) letters, programmer 
input in lower case. 



BACKGROUND 

Entering Data Under CMS 

Unless you are operating in a submode of CMS, such as INPUT mode within 
the editor, everything you enter at the terminal is taken to be a CMS 
command. if the command is correct, it is carried out and a READY 
message typed to confirm that the command is complete and that the 
system is ready for further commands. If the command is not correct, an 
error message is typed. Data is transmitted to the system when you press 
the carriage return key. 

When a CMS command is being executed, the terminal keyboard is locked 
so that you cannot enter any further data until the system is ready to 
receive it. 

Line editing characters 

VM/370 provides four characters to alter, delete, or split up the line 
you key in at the terminal. These four characters are known as line 
editing characters and are a, eJ, #, and " by default. For some 
terminals A becomes t or ( . They are removed from your input and 
treated as editing characters unless they are preceded by the escape 
character (see "Using line editing characters as normal characters" 
below). The line editing characters can be used to alter or delete 
lines before you press the carriage return key, or to enter a number of 
commands on one line to save time. 
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£g Igt J:D2„§„ J:iD§ ; ^ Y ou wish to delete a line you are typing and to 

reenter it completely you should use the logical line delete character 

and then press the carriage return key. By default the logical line 

delete character is ef. Thus to delete a line you might enter: 

this is an example of deleting a line 6 

it. becomes t or ( on some terminals.) 

Alterin3_a_line: If you wish to alter a line and then transmit it to 
the system, you must use the logical character delete character, 
(sometimes called the logical backspace character). By default the 
logical character delete character is a. If the logical character 
delete character is entered once it deletes the previous character, if 
it is entered twice it deletes the previous two characters, and so on. 
Thus to alter the line you are typing you might enter: 

this is an example of altering a wineaaaaiine 

Many programmers prefer to use the actual backspace key on the terminal 
as the character delete character. This saves the trouble of having to 
count back to the character you wish to change. Instead you can just 
backspace to the incorrect character and reenter the line from that 
point, re set the backspace as the character delete character you must 
use the terminal command thus: 

TERMINAL CHARDEL (you press the backspace key at this point) 

(Note: This cannot be done in EDIT mode.) 

Enter ing_more_than_gne_cgmmand_per ..line: If you want to save time at 
the terminal by entering more than one command per line you must use the 
logical line end character. By default this is #. The characters 
following the # are treated as a new line. The line end character can 
be used to split any type of input although its chief use is for 
commands. For example if you wanted to split a line you might enter: 

this is an example of splittingtta line 

Ij§iS3-A4Pg...g.^J:fe452....,gl3.§i! : ;^gfe.^.¥S-_.^§ flP^rcgl .characters : If you wish to use 
any of the line editing characters as a normal character you must 
precede it with the escape character. By default this is " . For 
example to enter the line 'this is an example of using the escape 
character to enter a* you would enter: 

this is an example of using the escape character to enter "a 

The escape character can be used preceding itself. 

A tt entign_k ey : If you press the attention key, or its equivalent once 
while under the control of CMS, it causes an attention interrupt. If a 
CMS command is being executed, this allows you to key in further CMS 
commands that will normally be executed when the current command has 
been completed. However, there are a number of commands that are 
executed immediately. These are called immediate commands. HT - halt 
typing, HX - halt execution and RT - resume typing can be useful when 
running PL/I programs. The immediate commnads are described in the 
Command Language User's Guide. 

If a CMS command is not being executed, pressing the attention key once 
deletes anything entered on the current line, but otherwise has no 
effect. 

If you press the attention button twice while in the CMS environment, 
control is returned to CP. The system then types "CP" at your terminal. 
If you wish to return to CMS, you can press the attention button again 
or enter the CP EEGIN command and control will be returned to CMS. 
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Profile EXEC 

When the first CMS command after IPL is executed, a CMS disk must be 
accessed. If the first command is an ACCESS command, the disk accessed 
will be the disk named in the ACCESS command. If any other command is 
used, the 191 disk will be accessed by default and set up as your A 
disk. 

When the first disk is accessed, the disk is searched for a CMS EXEC 
procedure with the name PROFILE. (An EXEC procedure is a set of CMS 
commands that, typically, carry out repetitive housekeeping tasks such 
as defining files. These commands are executed by calling the EXEC 
procedure.) If an EXEC procedure with the name PROFILE is found on the 
first disk accessed, it is automatically executed. Many installations 
use this feature to handle repetitive housekeeping tasks that need to be 
done at the start of every session. 

Information on issuing and writing a PROFILE EXEC is given in the VM/370 
Command Language Reference. 



SOURCES OF FURTHER INFORMATION 

3!2Ei£ Reference .source 

CMS background VM/370 Command Language User's Guide 

IPL command VM/370 Command Language User's Guide 

PROFILE EXECs VM/370 Command Language User's Guide 
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Entering the Program-The EDIT and FILE Commands 



SUMMARY 

To enter or alter a PL/I source program under CMS, it is necessary to 
use the CMS editor. You enter the EDIT command followed by the file 
name of your choice and the file type PLIOPT or PLI. You then use the 
editing facilities either to enter new input or, if you are updating, to 
alter the existing program. The facilities available for manipulating 
and altering text using the editor are not described in this manual. If 
you are not aware of them, you will find them in the CMS Edit Guide. 
The facilities for correcting lines before you press the carriage return 
key are described in the previous section under the heading "Line 
Editing Characters". 

When you are satisfied with your input or alterations, you use the 

FILE subcommand to create a CMS file that can be compiled using the 

PLIOPT command. In addition to creating a file, the FILE subcommand 
also ends the edit submode. 

If you are entering a new PL/I program you must choose a new filename 
which follows the CMS conventions. That is, the name can consist of up 
to eight characters, which may be any alphameric character plus the 
special characters $, a, and #. (Remember however that a and # are 
default line editing characters and special action may be required if 
you wish to use them. Also care should be taken not to choose a CMS or 
| CP command as a name, because this can cause problems if you wish to 
| create a module file.) If you are altering an existing program, you 
specify the existing filename. Your input must be typed in columns 1 
through 71. The editor will insert one blank to the left of your input 
so that the actual margins will be 2,72. You can type your input in 
either capitals or lowercase letters or any combination of the two. 

If you intend to execute your program under CMS, you should be aware 
of the special conventions and restrictions that apply to PL/I when it 
is used under CMS. These are listed in chapter 3 of this manual. If 
you intend to compile your program under CMS but to execute it under the 
control of OS then there are no special restrictions on the language you 
may use. 

Special_action_will be_ ,reguired_in__the_ .following, .circumstances 

1. If your program uses lower case character string constants. 

2. If you wish to use a *PROCESS statement. 

3. If you wish to use any of the line editing characters as normal 
characters in your program. The line editing characters are a, #, £, 
and " by default. 

| 4. If you wish to create a file of secondary input text for inclusion by 
| use of the %INCLUDE statement. 

The action is described under the heading "Special Considerations" 
below. 
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Examples of Use of the EDIT and FILE Commands 



EXAMPLE OF ENTERING A NEW PROGRAM 
Terminal Printout Notes and comments 



edit rabbit pliopt The EDIT command followed by file 

| name and file type. 

I 

NEW FILE: Message shows that you have no PLIOPT 

| file called "rabbit". 

I 

EDIT: Message shows you are in EDIT mode. 

I 

input INPUT subcommand causes the INPUT 

| mode to be entered. 

I 

INPUT: Message shows you are in INPUT mode. 
rabbit:proc options (main); PL/I must appear in columns 1 through 

display 71. 

(•the rabbit squeaks to the world*); 
end; 

Null line (carriage return only on a 

| line) causes return from INPUT to 

I EDIT mode. 

I 

EDIT: Message shows change of mode. 

I 

top Places the line pointer at the 

| top of the file. 

TOF Message shows pointer is at top of 

| file. 

I 

type * Have the contents of the file 

| displayed at the terminal. 

RABBIT: PROC OPTIONS (MAIN); 

DISPLAY (•THE RAEBIT SQUEAKS TO THE WORLD*); 
END; 

FOF Means end of file reached 

file FILE command results in your input 

j being stored with the filename and 

j type you specified. It also ends EDIT 

j mode. 

R; READY message indicates further 

I commands can be entered. 



Conventions: 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes in the right hand column. 

3. System response is in uppercase (capital) letters, programmer 
input in lowercase. 
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EXAMPLE OF ALTERING AN EXISTING PROGRAM 



Terminal Printout 



Notes and comments 



(This example assumes that you are correcting an error en line 10) 



edit dig pliopt 



EDIT: 



next 10 

I 
PHT EDIT(X) (A); 

I 
c/ht/ut 

PUT EDIT(X) (A); 
! 
I 

1 
file 



R; 



Issue EDIT command specifying exist- 
ing PLIOPT file "dig". 

System confirms that it is in EDIT 
mode with a copy of the file 
available. (If there was no PLIOPT 
file "dig" it would respond "NEW 
FILE:".) The line pointer is placed 
at the top of the file. 

Position line pointer to incorrect 

line. 

The tenth line beyond the original 

line pointer position is displayed. 

CHANGE subcommand. 

Corrected line displayed. For 

details of CHANGE and other edit 

subcommands see CMS Edit Guide 

FILE command requests that the 
altered copy be stored as the file 
"dig" and that the previous copy be 
discarded. 

READY message indicates further CMS 
commands may be entered. 



Conventions : 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes in the right hand column. 

3. System response is in upper case (capital) letters, programmer 
input in lowercase. 



BACKGROUND 



The EDIT Facility of CMS 



The EDIT facility of CMS allows you to create and update sequential 
files from your terminal. It is used to create PLIOPT or PLI files 
which can be compiled by the PL/I Optimizing Compiler. (PLI files were 
the filetype available for PL/I under CP/67 and can still be used under 
the VM/370 system. Their format is identical to PLIOPT files.) The EDIT 
facility has two modes, the EDIT mode and the INPUT mode. The EDIT 
mode allows you to use various EDIT subcommands to change, rearrange, or 
add to the copy of the file in main storage. The INPUT mode assumes 
that all items keyed in at the terminal are to be included in the file 
you are creating. To enter the INPUT mode, you issue the subcommand 
INPUT. To return from the INPUT mode to the EDIT mode, you enter a null 
line; that is, a line that consists only of a carriage return. (If you 
want a blank line in your PLIOPT file you must, therefore, key in at 
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least one blank in the line.) 

When you issue the EDIT command, you must specify a file name and a 
file type. CMS searches your disks for the file and if you have such a 
file brings a copy of it into main storage and types the message "EDIT:" 
indicating that you are in EDIT mode. If you do not have such a file, 
it assumes you intend to create one and types the message "NEW FILE" and 
"EDIT". To enter the INPUT mode you must enter the INPUT subcommand. 

To return from the EDIT mode to CMS, you must issue a command that 
specifies what is to be done to the copy of the file that you have been 
editing. This can be done by using either the FILE command or the QUIT 
command. The FILE command stores the copy of the file you have been 
creating and discards the previous copy, if any. The QUIT command 
discards the copy of the file that you have been editing. If you wish 
to retain both the original copy of the file and the copy of the file 
that you have been editing, you can use the FNAME subcommand to rename 
the copy of the file on which you are working. You could enter: 

fname rabbit2 

Then, when you issued the FILE command, the altered file would be stored 
with the name rabbit2 and the original file rabbit would still be 
available. 

If you wish to save your input and still remain in EDIT mode you can use 
the SAVE command. 

A full description of the EDIT command and EDIT subcommands is given 
in the VM/370 Edit Guide. 



Correcting Typing Errors 

If you wish to correct a line before pressing the carriage return key 
you can use the line editing characters described under the heading 
"Line Editing characters" in the previous section of this chapter. If 
you wish to correct a line when it has been transmitted, you must use 
the editing facilities which are described in the CMS Edit Guide. 



Format of PLIOPT files 

PLIOPT and PLI files created by the editor have 80 byte fixed length 
records. Sequence numbers are in columns 73 through 80. Further 
information can be found in the EDIT Guide. PLI files are an 
alternative type of file that can be handled by the optimizing compiler. 



SPECIAL CONSIDERATIONS 



Lowercase_Character _String_ Const ants 

When you are editing a PLIOPT file, the CMS editor automatically 
translates any lower case characters you enter to upper case. If ycu 
wish to enter lower case character string constants in your program it 
is necessary to take special action. Enter: 

CASE M 

This must be done when you are in EDIT mode. Your input will then be 



transmitted as entered. As the PL/I optimizing compiler accepts both 
upper and lowercase input, you can still enter your program in either 
uppercase or lowercase. During compilation the compiler will translate 
all PL/I into uppercase. Items appearing between quotes or comment 
delimiters will not be translated. The listing will show your program 
with everything except comments and data between quotes in upper case. 

To return to automatic translation to upper case during your edit 
session issue a CASE U subcommand. First enter a null line (carriage 
return only on a line) to return to the edit mode, then enter: 

CASE U 



Use of *PROCESS Statements 

Special action is required if you use the +PROCESS statement. This is 
because the * must appear in column 1 and, by default, the editor moves 
all input to PLIOPT files one column to the right. Accordingly the 
backspace key must be used before the *. The +PROCESS statement takes 
the form: 

(you press the backspace key)*process attributes xref; 

If you are using the backspace as a character delete character it must 
be preceded by the escape character. (See "Line Editing Characters" 
under "Invoking CMS - the IPL Command" earlier in this chapter.) 

Use of the line_editing characters in your program 

If you wish to use any of the line editing characters as normal input to 
your program you must precede them by the escape character. By default, 
the line editing characters are a, #, t, ", but all or any of them may 
be changed with the TERMINAL command, and £. becomes [ or ( on certain 
terminals. If the defaults are in effect, and you wish to refer to a 
variable called D0CUMENT#2, it is necessary to enter the #, which is the 
default line-end character, preceded by " which is the default escape 
character, thus: 

DOCUMENT" #2 

Details of the line editing characters are given in the previous section 
of this chapter under the heading "Line Editing Characters". 

I Creating a file,.f or inclusion bY_%INCLUDE - _statement 



If you wish to create a file of secondary input text that you will 
subsequently be able to include in your program by use of the %INCLUDE 
.statement, you will need to create a COPY file and to store it on a 
rracro library by use of the MACLIB command. 

Creating a copy file is similar to creating a PLIOPT file, however, 
data must be typed in columns 2 through 72 if you intend to use the 
standard PL/I margins. This is necessary because the text is not 
shifted one column to the right as it is for PLIOPT files. When you 
have created your copy file and used the FILE command to store it, you 
will need to issue a MACLIB command to place it on a macro library. The 
KACLIE corrmand takes the form: 

MACLIE | ADD) file-name macro-library-name 

\gen ] 

If you are adding a new file to an existing library you use "ADD" as the 
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second operand. If you are creating the macro library you use "GEN" as 
the second operand. An example of creating a file of inclusion by the 
use of %INCLUDE statements is shown below. 



EXAMPLE OF CREATING SECONDARY INPUT TEXT FOR INCLUSION 
EY % INCLUDE STATEMENTS 



edit cuckoo copy Filetype COPY must be used 
NEW FILE: 

EDIT: Enter EDIT mode 

input Enter INPUT submode 
INPUT: 
DISPLAY ( f TEST DATA FOR ^INCLUDE*); Column 1 must be left blank to 

j allow for standard PL/I margins 

I 

Null line causes return to EDIT mode. 

EDIT Return from INPUT to EDIT mode. 

file Store the file. 

R; 

maclib add mylib cuckoo Store the file on the macro library mylib. 

J If the macro library did not exist, you 

j would use "GEN" instead of "ADD" this 

j would generate a macro library called 

J "mylib". 

R; 

Conventions: 



1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accoirmodate notes in the right hand column. 

3. system response is in upper case (capital) letters, programmer 
input in lower case. 

L J 



SOURCES OF FURTHER INFORMATION 

Topic Reference, source 

Format of PLIOPT and PLI files CMS EDIT Guide 

Using the VM/370 editor CMS EDIT Guide 

Using your terminal CMS Terminal User's Guide 
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Compiling the Program-The PLIOPT Command 



SUMMARY 

To compile a program under CMS, you use the PLIOPT command followed by 
the name of the file that contains the source program. If you wish to 
specify any compiler or PLIOPT options, these must follow the file name 
and be preceded by a left parenthesis. Options are separated from each 
other by blanks, the abbreviated forms should always be used. 

During compilation, two new disk files will be produced. They will 
have the file types TEXT and LISTING and the same file name as the file 
specified in the PLIOPT command. The TEXT file contains the compiled 
code. The LISTING file contains the listings produced during 
compilation. Any error messages produced will be transmitted to your 
terminal. 

If compilation reveals source program errors, you can alter the 
PLIOPT file that contains the source by use of the CMS editor. You can 
then reissue the PLIOPT command. This results in the creation of new 
TEXT and LISTING files corresponding to the newly edited source program. 
If previous versions were available they will be overwritten. When you 
have a satisfactory compilation, you can execute the program, which is 
now in the form of a TEXT file. The next section of the chapter tells 
you how to do this. 

Special action will_be_reguired - in the following circumstances: 

1. If your source uses the %INCLUDE statement to incorporate secondary 
input text. 

2. if your source program is not on a CMS disk. 

3. If you intend to execute your program under the control of OS. 

| 4. if you wish to place the compiled program on a text library. 

The action required is described in the sections below under the 
heading "Special considerations." 
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Example of Use of the PLIOPT Command 



EXAMPLE OF USE OF THE PLIOPT COMMAND 



j Terminal Printout Notes and comments 

I 



pliopt rabbit (xref The PLIOPT command 

I I 

| | 1. Options must appear after a left 

I j parenthesis and be separated by blanks, 

j j If any exceed 8 characters see "Special 

Considerations" below. 



I I 



2. The right parenthesis is not necessary. 



j j 3. During compilation the system will 

j j issue an in-operation signal for every 

| j 2 seconds of virtual CFU time used, 

j j this is known as the BLIP signal. 

I I 

| NO MESSAGES PRODUCED FOR THIS COMPILATION 

| COMPILE TIME 0.01 MINS SPILL FILE RECORDS SIZE 4051 

! I 

|R; READY message. If the compiler failed or 

j | found errors of severity W or higher, CMS 

j j responds R (return code); 



Convent i ens : 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes in the right hand column. 

3. System response is in upper case (capital) letters, programmer 
input in lower case. 



IL- 



BACKGROUNE INFORMATION 

Compiler Output_and_its_Destinatign 

When you issue the PLIOPT command, CMS calls the PL/I Optimizing 
compiler to compile your source program. The compiler creates two new 
files during its execution. One file contains the compiled code that 
will be executed when you wish to execute your program. The other file 
contains diagnostic messages about the compilation, and, optionally, 
listings of your source program and the compiled code. (The various 
options controlling the listing produced by the compiler are described 
in chapter 3 of this manual.) 

By default, the two newly created files will be placed on CMS disks. 
They will have the same file name as the file that contains the source 
program but a different file type. The compiled code will have the file 
type TEXT and the listing will have the file type LISTING. Thus, if you 
compiled a PLIOPT file called ROBIN you would, by default, create two 
further files called ROBIN; a TEXT file containing the compiled code and 
a LISTING file containing the listing information. These files would be 
placed on your CMS disks according to the rules shown in figure 1.2. 
(The relationship between CMS disks is explained in the VM/37 Command 
Language User's Guide.) 
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The creation of the LISTING file can be suppressed by use of the 
NOPRINT option of the PLIOPT command. (See below under "Listing 
Options".) The creation of the TEXT file can be suppressed by use of 
the NOOBJECT option of the PLIOPT command. 



r "* 

j SOURCE DISK 

j source disk read/write 


OUTPUT DISK 
source disk 


============= 


j source disk read/only with 
| parent disk read/write 


parent disk 




j source disk read/only with 
j parent disk read/only and 
j A disk read/write 


A disk 




j source disk read only with 

| no parent and A disk read/write 


A disk 





source disk read/only with no program terminates unless you 
parent disk or parent disk have directed output to a non 

read/only and A disk read/ DASD device by using a CMS 

only FILEDEF command. (See CMS 

Command Language User's Guide 
for information on how to do 
this) 



Figure 1.2. The disks on which the compiler output is stored 



Choosing the Information to.be sent_to ygur_Terminal - Listing 
Options 

Options of the PLIOPT command and other CMS facilities offer you a wide 
choice in the amount of listing information that can be made available 
to you at the terminal. 

Three factors are relevant: 

1. The compiler option TERMINAL which allows you to have sections of 
the listing printed at the terminal as well as being included in 
the normal listing file. TERMINAL can be followed by a 
parenthesized options lists specifying those parts of the listing 
that you wish to be transmitted to your terminal. chapter 3 of 
this manual gives details. By default the TERMINAL option is 
specified without an options list and compiler diagnostic messages 
are transmitted to the terminal. 

2. The CMS option PRINT | DISK | NOPRINT , which allows you to direct the 
listing to a printer PRINT), to a CMS file (DISK... This is the 
default) or to have the listing file discarded (NOPRINT) . 

3. The ability to direct the listing information directly to the 
terminal by issuing the FILEDEF command "FILEDEF LISTING TERM" 

The TERMINAL and PRINT options are described in chapter 3 of this 
manual. The FILEDEF command is described in the VM/37 Command Language 
User's Guide. 

The CMS defaults are TERMINAL with no options list and DISK. When 
you have received the messages passed to your file as specified in the 
TERMINAL option, you can decide whether to examine the LISTING file 
using the EDIT mode, to pass it to a printer, or to discard it. 
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Only one copy of the listing is transmitted to the teririnal if you 
use both the TERMINAL option and assign the listing file to the 
terminal. 



compiler Options 



The PLIOPT command expects all options to be not more than eight 
characters long. It is therefore, necessary to use the abbreviated form 
of certain compiler options such as ATTRIBUTES, and advisable always to 
use the abbreviated form. All options and sub-options must be separated 
by blanks . Parentheses need not be separated from options or suboptions 
even if the option has a length of more than 8 characters. Thus 
TERMINAL (XREF A) is acceptable, although the total length is greater 
than 8 characters. -rs 



Files used by the compiler 



During compilation the compiler uses a number of files. These files are 
allocated by the interface module that invokes the compiler. The files 
used are shown in figure 1.3. 



Name 


Function 


Device Type 


When Required 


PLIOPT 


System input 


DASD, 

magnetic tape, 
card reader 


Always 




LISTING 


System print 


DASD, 

magnetic tape, 
printer 


Always 




TEXT 


System load 


DASD, 
magnetic tape 


When object 
be created 


module is to 


SYSPUNCH 


System punch 


DASD, 


When object 


module 






magnetic tape. 


required in 


card image 






card punch 


format 




SYSUTl 


Spill 


DASD 


When insufficient main 








storage available 


MACLIB 


Preprocessor 


DASD 


When %INCLUDE is used 




%INCLUDE 









L , J 

Figure 1.3. Files that may be used by the compiler 



SPECIAL CONSIDERATIONS 



Secondary Input Text - %INCLUDE Statements 



If your program uses %INCLUDE statements to include previously written 
PL/I statements or procedures, the libraries on which they are held must 
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be made available to CMS before issuing the PLIOPT command. To do this 
you must insert the statements into a CMS MACLIB using the MACLIB 
command. You then issue a GLOBAL command taking the form "GLOBAL MACLIB 
filename. " For example, if your secondary input text was held in MACLIB 
called "mylib" you would enter: 

global maclib mylib 

before issuing the PLIOPT command. The PLIOPT command must specify 
either the INCLUDE or the MACRO option. 



Source grogra^not^on a CMS Disk 



If your source program is not held on a CMS disk you can either read or 
move it to a CMS disk from a card reader or tape using the READCARD or 
MOVEFILE commands of CMS, or issue a FILEDEF command to define the EL/I 
source as coming from either the reader or tape device and then compile 
it. 

Moving the file onto a CMS disk offers the advantage that the source 
can subsequently be altered from the terminal. This may be necessary if 
compilation reveals errors in the source program. The method is given 
in the VM/370 Command Language User f s Guide. 

To compile a program held on card or tape it is necessary to issue a 
FILEDEF command before the PLIOPT command. Thus to compile a program 
held on card you might use the following sequence: 

FILEDEF PLIOPT READER (LRECL 8 RECFM F BLOCK 80 



PLIOPT fname (option 1 



option n) 



Any filename can be used for "fname". The name specified will be 
given to the LISTING, TEXT, and UTILITY files produced by the compiler. 

A description of the FILEDEF command is given in the VM/370 command 
language reference. 



CompJLling j _a_Program ,.,.to_be_Executed_UjQder OS 

If you intend to execute your program under OS, you should specify the 
OSDECK option thus: 

PLIOPT RAEBIT (OSDECK 

This prevents the compiler from issuing a CMS loader ENTRY command, 
specifying the CMS execution time interface module. An attempt to 
execute a program compiled without the OSDECK option under OS, results 
in an OS linkage editor error of severity level 8. 

It is possible to execute a program compiled with the OSDECK option 
under CMS, but special action is required. See "Executing a File not 
Compiled Under CMS or Compiled with the OSDECK option" in the following 
section, "Executing a PL/I Program." 



1 Compiling a , prqgram_tO M be_placed on„a text library 

I 

| If you intend to include the compiled TEXT file as a member of a text 

| library it is necessary to use the NAME option when you specify the 

I PLIOPT command. This is because members of a TXTLIB file are given the 
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\ name of their primary entry point if they have no external name. The 
| primary entry point of every TEXT file produced by the optimizing 
I compiler is the same, consequently only one compiled program can be 
j included in a TXTLIB if the NAME option is not used. (The NAME option 
| gives the TEXT file an external name.) 

i Code required to create a TEXT file suitable for including in a 

j| TXTLIB is shown below. This code gives the file the external name used 

I in the PLIOPT command. However any other name can be used, provided 

i| that it does not exceed six characters. It should ne noted that, if the 

!| name exceeds six characters the NAME option will be ignored. 

i 

I The code below compiles a PLIOPT file RABBIT with the external name 
| RABBIT and adds it to an existing text library called BIOLIB. 

I 

| pliopt rabbit (name (• rabbit* 

i 

j (compiler messages etc) 

1 

] txtlib add biolib rabbit 



SOURCES OF FURTHER INFORMATION 



Topic 

Error message explanations 
CMS (numbered DMSxxxx) 

PL/l (numbered iELxxxx) 

FILEDEF command 

GLOBAL command 

MOVEFILE command 

PL/I language 

PLIOPT command 
READCARD command 
TXTLIB command 



Reference source 

VM/370 system Messages Manual 

PL/I Optimizing Compiler Messages 

VM/370 Command Language User's Guide 

VM/370 Command Language User's Guide 

VM/370 Command Language User*s Guide 

PL/i Checkout and Optimizing Compilers 
Language Reference Manual 

Chapter 3 of this manual 

VM/370 Command Language Reference 

VM/370 Command Language Reference 
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Executing a PL/I Program 



SUMMARY 

To execute a PL/I program under CMS, you must have either a CMS TEXT 
file or a CMS MODULE file. If your program is not in either of these 
forms, see the earlier sections of this chapter. (A MODULE file is 
created by using the LOAD command to resolve addresses in a TEXT file. 
Details are given below. ) 

If you have a TEXT file execution requires three steps: 

1. Issuing a GLOBAL command for the PL/I libraries. 

2. Issuing the LOAD command with the START option if you wish 
execution to begin. 

3. If the START option was not issued with the LOAD command,, 
issuing the START command. 

These steps are shown in example 1 below. 

If you have a MODULE file execution requires 2 steps: 

1. Issuing a GLOBAL command for the PL/I libraries. 

2. Issuing the filename as a CMS command. 
These steps are shown in example 3 below. 

To create a MODULE file, you issue the GENMOD command after issuing the 
J GLOBAL and LOAD commands, see example 2 below. You must specify a 
| filename with the GENMOD command, otherwise the resulting module file 

will be called DMSIBM. 

The PL/I standard files, SYSIN, SYSPRINT, and PLIDUMP are automatically 
assigned before the PL/I program begins execution. SYSIN and SYSPRINT 
are assigned to the terminal, and PLIDUMP is assigned to a printer. If 
you wish to override these assignments you must issue FILEDEF commands 
before the start of execution. See "PL/I Files and CMS Defaults" below. 

Spgcial„actign_will m be_reguired_in_t circumstances: 

1. If you wish to pass parameters to your program. 

2. If your program uses any PL/I files that do not match the CMS 
default definitions. 

3. if you wish to execute a program that was compiled under OS, or was 
compiled under CMS with the OSDECK option. 

The action required is described in the sections below under the heading 
"Special Considerations." 
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Examples cf Executing a ^PL/ I Program 



EXAMPLE 1. EXECUTING A TEXT FILE 
Terminal printout Notes and comments 



global txtlib plilib 



Re- 



load rabbit 
I 



R; 

I 
start 



EXECUTION BEGINS.. 



THE RAEBIT SQUEAKS TO THE 
WORLD 



R; 

I 



GLOBAL command makes the PL/I libraries 
available. 

READY message. 

LOAD command generates an executable 
program in main storage from the TEXT 
file. (An alternative is 

LOAD RABBIT (START, if you want immediate 
execution) . 

READY message. 

START command starts execution 

1. if you wish to pass parameters, follow 
"start" with a blank, an asterisk, 
another blank, and then the parameters; 
thus: start * / 123. See "Special 
Considerations'* below. 

Message at start of execution. For every 
2 seconds of CPU time used an in-operation 
signal is given. 

The message in the sample program is 
passed to the terminal. 

The READY message indicates that further 
CMS commands may be entered. 



Conventions : 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes in the right hand column. 

3. system response is in upper case (capital) letters, programmer 
input in lower case. 
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EXAMPLE 2. CREATING A MODULE FILE 



Terminal Printout 



Notes and Comments 



global txtlib plilib 

I 

R? 

load rabbit 

I 



genmod rabbit 



Re- 
conventions: 



Make PL/I libraries available 



LOAD command creates an executable 
program from TEXT file and library 
modules. 

Creates a copy of the loaded program 
as a CMS MODULE file. This can now 
be executed by use of the file name 
as a command. If you issue a genmod 
command without a filename the 
resulting file will be called DMSIBM 
because this is the name of the first 
entry point in every module file 
produced by the compiler. 



1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes in the right hand column. 

3. system response is in upper case (capital) letters, programmer 
input in lower case. 
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EXAMPLE 3. EXECUTING A MODULE FILE 



Terminal Printout 



Notes and coirments 



global txtlib plilib 

I 

I 

I 

I 
R; 

I 
rabbit 

I 
1 
I 



GLOBAL command makes the PL/I 
libraries available. This is 
necessary as some library modules are 
loaded dynamically. 

READY message 

For a MODULE file the filename can be 
used as a CMS command. 

1. If you wish to pass parameters, 

| they must appear after the file- 

| name and be preceded by a blank 

j thus: rabbit / 1234. See "Special 

| Considerations" below. 

I 

THE RABBIT SQUEAKS TO THE WORLD The message in the sample program is 
j passed to the terminal. 



R; 



The READY message indicates that 
further CMS commands may be entered. 



C°£ve nt ions : 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added to 
accommodate notes. 

3. System response is in upper case (capital) letters, programmer 
input in lower case. 



BACKGROUND 



MODULE and TEXT Files 



During compilation the PL/I optimizing compiler produces code that 
requires further processing before it can be executed. Addresses within 
the code must be resolved and external modules referenced within the 
code must be included. These references will always include modules 
from the PL/I library. 

The resolution of addresses is initiated by the LOAD command. The 
processed data can then be retained with the addresses resolved by the 
use of a GENMOD command specifying the filename. This command produces 
a CMS MODULE file that can be executed without going through the process 
of issuing the LOAD command on each occasion. 



PL/ I Files and CMS Defaults 



The FILEDEF command gives the CMS user the ability to simulate OS DD 
statements when using CMS. The use of FILEDEF statements is necessary 
for any PL/I programs that use record or stream I/O statements. (It is 
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possible to use the DISPLAY statement and the REPLY option to simulate 
conversation I/O under CMS. See chapter 2.) 

To assign the terminal to a file it is necessary only to use TERM in 
your FILEEEF command. For example if you wished to assign a file called 
CUTPUTl to the terminal you would do it as follows: 

FILEDEF OUTPUTl TERM 

Because synchonization is only automatically handled for STREAM files, 
RECORD files should not normally be assigned to the terminal. 

A number of FILEDEF commands are issued by the interface module 
DMSIBM. They assign SYSIN and SYSPRINT to the terminal for 
conversational I/O and PLIDUMP to a printer. If you wish to override 
these default assignments, you must issue suitable FILEDEF commands 
before starting the execution of the PL/I program. 

The differences in syntax between the FILEDEF command and the OS DD 
statement are considerable and the user should consult the VM/370 
Command Language User's Guide before attempting to use the FILEDEF 
command. If the FILEDEF command is not used and an attempt is made to 
open the file CMS defaults are applied. The default is a FILEDEF 
command to device disk with filename FILE and file type ddname. 



An Alternative Method of Executing a MODULE File 

A module file can be executed by a LOADMOD command followed by a START 
command. 



SPECIAL CONSIDERATIONS 

Passing_parameters_and Exec ution_Time. Options 

When passing parameters two sets of restrictions have to be born in 
mind, those that are imposed by CMS, and those imposed by the PL/I 
optimizing compiler. 

Under CMS, parameters must be passed to the program in tokens 
containing no more than eight characters. These tokens must be 
separated by blanks. 

The PL/I optimizing compiler allows you to pass two types of 
parameters to a PL/I program. The first is a set of execution time 
options, sometimes called program management parameters (these are 
listed in chapter 4 of this manual) . The second is a single parameter 
that is passed to the PL/I main procedure. The two types of parameter 
are separated by a / symbol which must itself have a blank on either 
side. Anything preceding this symbol is taken to be an execution time 
option. if no execution time option is passed, the main procedure 
parameter must be preceded by the three characters 
blank, oblique stroke, and blank ( / ). 

Under the PL/I Optimizing Compiler, the main procedure parameter must 
be a character string, and, because blanks are used as delimiters in CMS 
blanks cannot be passed in the string. Blanks are removed from the 
string and the two separated items concatenated. 

Suppose you wished to pass to a program the execution time options 
NOSPIE AND REPORT and a character string consisting of a name of more 
than eight characters and three sets of figures, this could be passed in 
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the form: 

Start * NOSPIE REPORT / CARPENTE R,38,24, 38 

this would be passed to the program in the form of 

CARPENTER , 38 , 24, 38 

Executing a File Not Compiled Under CMS or Compiled with_the_OSDECK_Op_tion 

If you wish to execute under CMS a program that was compiled under OS 
or was compiled under CMS with the OSDECK option, it is necessary to 
explicitly load the execution time interface module. (An entry 
statement for this module is automatically included in the TEXT file for 
any PL/I program compiled under CMS without the OSDECK option.) 
Assuming the program that you wish to execute is on a CMS TEXT file and 
is called SEAGULL, the following commands are required. 

global txtlib plilib 
load seagull dmsibm 
start dmsibm 

The GLOEAL and LOAD commands make the PL/I library available and load 
the program and the interface module. The START command passes control 
to the interface module, which, in turn, passes control to the program. 

If you wish to create a MODULE file from the load module you have 
created, you must issue a GENMOD command after the LOAD command. This 
will produce a MODULE file with the name of the file used in the LOAD 
command (SEAGULL in the example). The MODULE file can then be executed 
in the normal manner. 

SOURCES OF FURTHER INFORMATION 



Topic 

FILEDEF command 
filename as a command 
GENMOD command 
GLOBAL command 
LOADMOD command 
START command 



Bg£erence^Sou-rcg 

VM/370 Command Language User , s Guide 
VM/370 Command Language User's Guide 
VM/370 Command Language User's Guide 
VM/370 Command Language User's Guide 
VM/370 Command Language User's Guide 
VM/37 Command Language User's Guide 
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Ending the Terminal Session-The LOGOUT Command 



SUMMARY 

To end a CMS session you enter the CP LOGOUT command from the CMS or the 
CP environment. 

Before finishing the session you may wish to erase some of the files. 
This is done by using the ERASE command. 

§P§S.4,gl^gg^i2D-.w41.J:^^g.-^gg]ji£g^-4.f-.X213.-§^g-B?.JLDg[ ,. a _gwitched m line 
S2QDg^i2D.- a ?2^-Y21j-.^9-QQ^-^4§b-to..he .disconnected. See "Special 
Considerations" below. ""' 



Example of .ending „.the_ session 

r " ' ~ "" 

EXAMPLE OF LOGOUT 

Terminal Printout Notes and comments 

logout You enter the LOGOUT command. 

CONNECT=hh:mm:ss VIRTCPU=mm.SS.ss TOTCPU=mm: ss. ss 



Message tells you the connect time 
The actual length of the session, 
and virtual and the real CPU time in 
minutes, seconds, and hundredths 
of seconds. 
LOGOUT AT hh:mm:ss (zone) dayr-of-week mm/dd/yy 

Message shows time and date of 
| logging off. 

(you switch off terminal) 



Conventions: 

1. A carriage return is assumed after all programmer input. 

2. The character | in column two implies spacing has been added. 

3. System response is in upper case (capital) letters, programmer 
input in lower case. 



EACKGROUND 



Deleting Files 

If you wish to delete files you use the ERASE command. The command must 
specify the file name and the file type. For example if you wished to 
delete the PLIOPT file "rabbit", you would enter: 

erase rabbit pliopt 
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If you wished to delete all the files called "rabbit" you would enter: 
erase rabbit * 



SPECIAL CONSIDERATIONS 



Retain ing.,a Switched ..Line ..Connection 

If you are using a switched line to a computer, the use of the LOGOUT 
command as shown results in the connection to the computer being broken. 
If you wish to retain the connection, you must enter "logout hold". The 
action is the same as for logout except that the switched line is not 
disconnected. 



SOURCE OF FURTHER INFORMATION 

Top„ic Refer encg_source 

ERASE comirand VM/37 Command Language User's Guide 

LOGOUT command VM/37 Command Language User's Guide 
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Chapter 2: PL/I Conventions and Restrictions Under 
CMS 

Restrictions 

The PL/I features that may not be used under CMS and restrictions on 
other features are shown in figure 2.1. 

r ^ 

DO NOT USE UNDER CMS 

ASCII data sets 

BACKWARDS attribute with magnetic tapes 

FETCH and RELEASE statements 

INDEXED files 

PL/I checkpoint restart facilities (PLICKPT) 

PL/I sort facilities (PLISORT) 

Tasking 

Teleprocessing files 

VS or VES record formats 

VSAM files 



OTHER RESTRICTIONS UNDER CMS 



READ. .. .EVENT can only be used if the NCP parameter is included in 
the ENVIRONMENT option of the PL/I file. 

| j Blanks cannot be passed in the parameter string to the main 

procedure. The blanks are removed from the string and 
| | the items separated by them are concatenated. 

i „ j 

Figure 2.1. Restrictions on the PL/l that can be executed under CMS. 

The results of using PL/I features that are not available under CMS are 
summarized below. 

MULTITASKING PL/I error message number IBM576I will be generated. 
This reads "ATTEMPT TO CALL A TASK IN NON-TASKING 
ENVIRONMENT" The associated ONCODE is 3 915. 

SORT The ERROR condition will be raised and PL/I error 

message 8811 will be generated. This reads "SORT/MERGE 
NOT SUPPORTED IN CMS". The associated CNCODE is 9201. 

FETCH/RELEASE The ERROR condition will be raised and PL/I error 
message 5921 will be generated. This reads 
"FETCH/RELEASE NOT SUPPORTED IN CMS". The associated 
ONCODE is 9252. 

CHECKPOINT/RESTART 

PL/I error message 9261 will be generated and execution 
will continue without a checkpoint being taken. The 
message reads "CHECKPOINT RESTART NOT SUPPORTED IN 
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CMS". There is no ONCODE as the ERROR condition is not 
raised. 

ISAM FILES The UNDEFINEDFILE condition is raised. 

Use of TCAM, or spanned records on BDAM, or the BACKWARDS attribute. 

CMS error message number DMSOP063E will be generated. 
This reads "OPEN ERROR CODE x ON ddname." 
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Conventions 

Two types of convention apply to PL/I when used under CMS. The first 
are those adopted to make input/output simpler and more efficient at the 
terminal. The second type are those that result from the terminal being 
considered as the console of a virtual machine. These affect the DISPLAY 
statement and the REPLY option. 

No prompting or other facilities are provided for record I/O at the 
terminal. You are therefore strongly advised to use stream I/O for any 
transmission to or from a terminal. 



STREAM I/O CONVENTIONS AT THE TERMINAL 

To simplify input/output at the terminal various conventions have been 
adopted for stream files that are assigned to the terminal. Three areas 
are affected. 

1. The formatting of PRINT files 

2. The automatic prompting feature 

3. The spacing and punctuation rules for input 

Formatting Conventions for PRINT Files 

When a PRINT file is assigned to the terminal, it is assumed that it 
will be read as it is being printed. Spacing is therefore reduced to a 
minimum to reduce printing time. The following rules apply to the PAGE, 
SKIP, and ENDPAGE keywords. 

• PAGE options or format items result in three lines being skipped. 

• SKIP options or format items larger than SKIP (2) result in three 
lines being skipped. SKIP (2) or less is treated in the usual manner. 

• The ENDPAGE condition is never raised. 

Overriding the formatting conventions for PRINT files: If you wish 
normal spacing to apply to output from a PRINT file at the terminal, it 
is necessary to supply your own tab table for PL/I. This is done by 
declaring an external structure called PLITABS in the program and 
initializing the element PAGELENGTH to the number of lines that can fit 
on your page. This value differs from PAGESIZE which defines the number 
of lines you want to be printed on the page before ENDPAGE is raised, 
see figure 2.2. If you required a pagelength of 64 lines you would 
declare PLITAES thus: 

DCL 1 PLITAES STATIC EXTERNAL, 

( 2 OFFSET INIT (14), 

2 PAGESIZE INIT (60), 

2 LINESIZE INIT (120), 

2 PAGELENGTH INIT (64), 

2 FILL1 INIT (0) , 

2 FILL2 INIT (0), 

2 FILL3 INIT (0), 

2 NUMEER_OF_TABS INIT (5), 

2 TAB1 INIT (25) , 

2 TAB2 INIT (49), 



Chapter 2: PL/I Conventions and Restrictions Under CMS 37 



2 TAB3 INIT (73) , 
2 TABU INIT (97), 
2 TAB5 INIT (121)) FIXED BIN (15,0); 

This declaration gives the standard page size, line size and tabulating 
positions. 



PAGESIZE < 



\ 
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> PAGELENGTH 



PAGE LENGTH: is the number of lines that could be printed on a page. 

PAGESIZE: is the number of lines that will be printed on a page before the 
ENDPAGE condition is raised. 



Figure 2. 2. PAGELENGTH defines the size of your paper, PAGESIZE 
the number of lines printed in the main printing area. 



Automatic Prompting 

When the program requires input from a file that is associated with a 
terminal, it issues a prompt. This takes the form of printing a colon on 
the next line and then skipping to column 1 on the line following the 
colon. This gives you a full line to enter your input thus: 

(space for entry of your data) 

This type of prompt is referred to as a primary prompt. 

If the data you transmit from the terminal does not complete the 
requirements of the GET statement, a further prompt is issued. This 
takes the form of printing a plus sign followed by a colon thus; 

+: (space for entry of your data) 

This type of prompt is referred to as the secondary prompt. 
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Qyg.¥?i^iQg m ^^gmatic_ProrriEting: It is possible to override the primary 
prompt by making a colon the last item in the request for the data. The 
secondary prompt cannot be overridden. Take the two PL/I statements 

PUT SKIP EDIT (• ENTER TIME OF PERIHELION* ) ; 
GET EDIT (PERITIME) (A (10)); 

As they stand they would result in the terminal printing 

ENTER TIME OF PERIHELION 
: (automatic prompt) 

(space for entry of data) 

However, if the first statement had a colon at the end of the output 
thus: 

PUT EDIT (•ENTER TIME OF PERIHELION:*) (A); 

the sequence would be: 

ENTER TIME OF PERIHELION : (space for entry of data) 

Note: The automatic-prompt override works by maintaining a check on the 
last item transmitted to your terminal. If the last item in the current 
session was a colon, the prompt will be overridden. Care should 
therefore be taken not to override the automatic prompt by mistake. If 
a program relies on automatic prompting at one point and overrides 
automatic prompting at another, problems are likely tc arise. This is 
because the prompt override stays in force not for one GET statement but 
for all GET statements until data that does not end with a colon is 
transmitted to the terminal. 



Spacing and Punctuation_Conyentions_for_Input 

Line continuation_character. If you wish to transmit as one data item 
data that requires 2 or more lines of space at the terminal a hyphen 
must be typed as the last character in each line except the last line. 
For example, if you wanted to transmit the sentence "this data must be 
transmitted as one unit" you could enter: 

this data must be transmitted - 
as one unit. 

Transmission would not occur until the carriage return after the word 
"unit". The hyphen would be removed. The item transmitted is referred 
to as a "logical line". 

Note: This convention means that a line whose last character is a hyphen 
or a PL/I minus sign can only be transmitted by entering two hyphens at 
the end of the line and following them by a carriage return only en the 
next line thus: 



xyz — 

(carriage return only on this line.) 



Simplified Punctuation for GET LIST and GET DATA Statements 

For GET LIST and GET DATA statements, a comma is added to the end of 
each logical line transmitted from the terminal if it is omitted by the 
programmer. Thus there is no need to enter blanks or commas to delimit 
items if they are entered on separate logical lines. For the PL/I 
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statement GET LIST(A,B,C); you could enter at the terminal. 

1 

+ :2 
+ :3 

However this rule also applies when entering character string data. A 
character string must therefore be transmitted as one logical line, 
otherwise commas are placed at the break points. For example, if you 
entered: 

•COMMAS SHOULD NOT BREAK 
+: UP A CLAUSE* 

The resulting string would read 'COMMAS SHOULD NOT BREAK, UP A CLAUSE* 

Automatic Padding for GET EDIT; For a GET EDIT statement there is no 
need to enter blanks at the end of the line. The item will be padded to 
the specified length. Thus for the PL/I statement GET EDIT (NAME) 
(A(15)); you could enter SMITH followed immediately by a carriage 
return. The item would automatically be padded with ten blanks so that 
the program received the fifteen characters "SMITH 

Note: This means that a single item must be transmitted as a logical 
line, otherwise the first line transmitted will be padded with the 
necessary blanks and considered to be the complete item. 

Use of SKIP for terminal input: SKIP in a GET statement has little 
meaning if the file involved is allocated to a terminal. The program is 
apparently being asked to skip data that has not yet been keyed in. For 
this reason, all uses of SKIP for input are taken to be SKIP(l) when the 
file is allocated to the terminal. SKIP(l) is treated as an instruction 
to ignore all unused data on the currently available logical line. 



Endfile 

The end of file can be entered at the terminal by keying in a logical 
line that contains the characters "/*" followed by a carriage return. 
Any further attempts to use the file without closing it and re-opening 
it result in the ENDFILE condition being raised. 



DISPLAY AND REPLY UNDER CMS 

Because the terminal is considered to be the console of the virtual 
machine, the DISPLAY statement and the REPLY option can be used to 
create conversational programs. The DISPLAY statement transmits the 
message to your terminal, and the REPLY option allows you to respond. 
For example, the PL/I statement: 

DISPLAY (*ENTER NAME*) REPLY (NAME); 

would result in the message "ENTER NAME" being printed at your terminal. 
The program would then wait for your response and your data would be 
placed in the variable NAME after you pressed the carriage return key. 
The terminal printout would look like this: 

ENTER NAME 
JOHN TAYLOR 
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Chapter 3: The PLIOPT Command and its Options 



How to Use This Chapter 

This chapter shows the syntax of the PLIOPT command, the options that 
can be used with the command, and the standard defaults that will apply 
if you do not specify values for certain options. 

There are five sections: 

1. A summary of the syntax notation used. 

2. A description of the PLIOPT command and its options showing the 
default option values suggested by IBM. 

3. A discussion of two general points. First the differences 
between options of the PLIOPT command and options of the PL/I 
Optimizing compiler, and, second, the relationship between the 
various statement numbering options. 

4. A table of options listed by function. 

5. An alphabetical list of options with detailed descriptions and 
syntax notation. 

If you wish to accept the default options, you will only need to look 
at the section on the PLIOPT command and possibly the section on syntax 
notation if you are not already familiar with this. It should be noted 
that the default values may have been altered by your installation and 
may not correspond to those shown in the table. If you wish to look up 
a particular option, you should look for it in the alphabetical section. 
If you want a summary of the options that are available, or if you are 
looking for an option to serve a specific purpose, you should look in 
the table of options listed by function. Eefore using an option found 
in this table you should check in the alphabetical section to discover 
the syntax. 

If you intend to use options in a *PROCESS statement, you should read 
the discussion headed "PLIOPT Options and Compiler Options". It should 
not be necessary to read the section headed "Relationship of Statement 
Numbering Options" unless you need amplification of the information 
supplied in the descriptions of the statement numbering options in the 
alphabetical section. 

A general discussion of the PLIOPT command is given in chapter 2 
under the heading "Compiling the Program the PLIOPT Command". 



Syntax Notation 

The syntax notation used to illustrate the command in this part of the 
manual is the same as that used in the VM/370 Command Language User's 
Guide. Briefly, the conventions are as follows: 

Items in brackets [ ] are optional. 

Items in braces { } are alternatives; choose only one. 

An item underlined applies unless an alternative is specified. 

Note: Defaults shown are suggested defaults and may have been changed 
for your system. 
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Items written in uppercase (capital) letters are keywords and must be 
spelled as shown. 

Items written in lowercase letters must be replaced by appropriate names 
or values . 

Separate the command name from the operands, options and suboptions by 
one or more blanks. 

The four special characters • ()* (single quote, left parenthesis, right 
parenthesis and asterisk) must be included where shown. 
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PLIOPT Command 

The PLIOPT command invokes the PL/I Optimizing Compiler to compile a 
program written in PL/I source language. The compiler produces a TEXT 
file containing machine code and a LISTING file containing listings and 
diagnostics. Other files may be produced depending on compiler options. 



Format: 



PLIOPT 



filename [ (optionl [option2] ...[)] ] 



Options; 



AG | NAG 

A|NA 

CHARSET ( [48 160] [EBCDIC 1 BCD] ) 

COMPILE | NC [ ( W | E | S ) ] 

CONTROL ( 'password 1 ) 

COUNT|NOCOUNT 

DECK | NODECK 

DUMP 1 NODUMP 

ESD | NOESD 

FLAG [ ( I | W | E | S ) ] 

FLOW[(n m>] I NOFLOW 

GONUMBERJNGN 

GOSTMT 1 NQGOSTMT 

INCLUDE | NINC 

IMPINIMP 

INSOURCE|NIS 

LC(n) |LC(55) 

LIST[(m n)3 INOLIST 

LMESSAGE jSMESSAGE 

MACRO | NOMACRO 

MAP I NOMAP 

MARGINK'c*) |NMI 

MARGINS(m n[c]) {MARGINS (2 72) 

MDECK | NOMDECK 

NAME ('name*) 

NEST1NONEST 

NUMBER | NONUMBER 

OBJECT | NCCBJECT 

OFFSET 1 1 NCOFFSET 

OPTIMIZE(TIME|0|2) | OPTIMISE (TIME | | 2) |NOPT 

OPTIONS | NOOPTIONS ; 

OSDECK *■ 

PRINT | DISK | NOPRINT ± 

SEQUENCE (m n) | NOSJIC^JENCE 

size ( y yyy y y yy I yy yyyKjMAX ) 

SOURCE | NOSOURCE 

STMT I NCSTMT 

STORAGE | NSTG 

SYNTAX | NSYN [ ( W | E j S ) ] 

TERMINAL [ ( opt- 1 ist ) ] | NTERM 

XREF I NOXREF 



^Note: These are options of the PLIOPT command and not 
compiler options, see discussion below. 



filename 



Is the name of the file that contains the PL/I source program. The 
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file type must be PLIOPT or PLI. 



optionl option2 



are a series of compiler or PLIOPT options- They must be 
separated from each other by at least one blank. The right 
hand parenthesis is optional. If contradicting options are 
specified, the rightmost option applies. 



USAGE 

The PLIOPT command compiles a PL/I program or a series of PL/I programs 
into machine language object code. If the program is held as a CMS file 
on disk it must have the file type PLIOPT or PLI. If it is not on disk, 
it must be defined to the system with a FILEDEF command. 

The options governing compiler operation and output are specified in any 
order. Any combination of options is accepted. When conflicting options 
are specified, the last specified option is used. The majority of 
options have positive and negative forms one of which is used by default 
if neither form is specified. Figure 3.1 summarizes the compiler 
options by function and enable you to quickly grasp the possibilities 
available with the PL/I Optimizing Compiler. 



PLIOPT OPTIONS AND COMPILER OPTIONS 

The majority of options of the PLIOPT command are options of the 
optimizing compiler. This means that they can be specified in the 
♦PROCESS statement as well as in the PLIOPT command. All options 
except DISK, NOPRINT, OSDECK, and PRINT can be specified in the * 
PROCESS statement. DISK, NOPRINT, OSDECK, and PRINT cannot be specified 
because they are PLIOPT options and not a compiler options. DUMP cannot 
be specified in the * PROCESS statement unless it is also specified in 
the PLIOPT command. This is because extra space must be acquired for 
the DUMP option before the * PROCESS statement is processed. 

Where options of the PLIOPT command contradict those of the *PROCESS 
statement, the options in the * PROCESS statement override those in the 
PLIOPT command. For options whose length is greater than eight 
characters, the abbreviation for that option must be used in the PLIOPT 
command. 



Relationship of _Statement_ .Numbering Options 

The optimizing compiler provides two methods of numbering statements. 
Statements can have their numbers taken from the sequence field of the 
record; this is the method used when NUMBER or GONUMBER is specified and 
is the default for CMS. Alternatively, they can be numbered 
sequentially starting from 1; this is the method used when STMT or 
GOSTMT is specified. 

The numbers of the statements are used in compiler diagnostic messages 
and listings. If the GONUMBER or GOSTMT option is specified, the 
numbers are retained in a table generated by the compiler and are used 
in execution time diagnostic messages. When numbers are required during 
execution, the same numbering system as that which applied during 
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compilation will be used. This means that specifying certain options 
implies that certain other options will be used. Three rules apply: 

1. Because one or other statement numbering system must be used during 
compilation, NOSTMT is taken as equivalent to NUMBER, and 
similarly, NONUMBER is taken as equivalent to STMT. 

2. Because the same numbering system must be used during compilation 
and execution, either of the GO options is taken to imply that the 
corresponding numbering system is to apply during compilation. 
Thus GONUMBER implies NUMBER and GOSTMT implies STMT. 

3. It is not possible to use both numbering systems in one compilation 
therefore GOSTMT implies NOGONUMBER, and GONUMBER implies NOGOSTMT. 

If contradictory options are specified, the last option found is used 
and any implications are taken from that option. 

The use of GONUMBER or GOSTMT involves a space overhead because the 
numbers are retained in a table generated by the compiler. If statement 
numbers are not retained into execution, execution-time diagnostic 
messages identify the location of the error by an offset from a 
procedure entry point. The use of the OFFSET option results in the 
generation of a listing at compile time that associates statement 
numbers with offsets and consequently enables you to identify the PL/I 
statement mentioned in an execution time error message. 

The OFFSET option is separate from the numbering options and must be 
specified if required. 
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- - n 
OPTIONS LISTED BY FUNCTION PART 1 1 


LISTING OPTIONS 




Control destination of listing file 




PRINT | DISK | NOPRINT* 

Control listings 

produced AGGREGATE 


Determine whether listing | 
goes to printer, CMS disk, or j 
is discarded. j 

list of aggregates and their j 
sizes. j 


ATTRIBUTES 


list of attributes of all J 
identifiers. j 


ESD 


list of external symbol j 
dictionary. j 


INSOURCE 


list of preprocessor input. | 


FLAG(I|W|E|S) 


suppress diagnostic messages j 
below a certain severity. | 


LIST 


list of compiled code produced | 
by compiler. j 


MAP 


list contents of static control | 
section produced by compiler. j 


OPTIONS 


list of options used. J 


SOURCE 


list of source program or j 
preprocessor output. | 


STORAGE 


list of storage used. | 


XREF 


list of statements in which eachj 
identifier is used. j 


Improve readibility of source listing 




NEST 


indicates do-group and block | 
level by numbering in margin. j 


MARGINI 


highlights any source outside | 
margins. j 


Control lines per page of listing 




LINECOUNT 


specifies number of lines per j 
page on listing. | 


* Options marked thus are ignored if 


used in the +PROCESS statement j 



Figure 3.1. (Part 1 of 3) Compiler options arranged by function 
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OPTIONS LISTED EY FUNCTION PART 2 



INPUT OPTIONS 

To define character set and margins of input 

CHARSET identify the character set used 

in source. 

MARGINS identify the columns used for 

source program, and 
identify position of a carriage 
control character 

SEQUENCE identify the columns used for 

sequence numbers. 



OPTIONS TO PREVENT UNNECESSARY PROCESSING 

Control whether compilation should end if errors above a certain level 
are found 

NOSYNTAX(W |E |S) stop processing after errors are 

found in preprocessing. 



NOCOMPILE(W|E|S) 



stop processing after errors are 
found in syntax checking. 



OPTIONS FOR PREPROCESSING 

MACRO 

INCLUDE 

MDECK 



allows full use of the 
preprocessor facility. 

allows inclusion of text without 
overheads incurred MACRO. 

produces a source deck from 
preprocessor output. 



OPTIONS TO USE WHEN PRODUCING AN OBJECT MODULE 

OBJECT 



NAME 



DECK 



produce an object module from 
translated output. 

specify the name of the object 
module produced. 

produce an object module on 
punched cards. 



OPTIONS TO CONTROL STORAGE USED 

SIZE 



controls the amount of storage 
used by the compiler. 



OPTIONS TO IMPROVE USABILITY AT A TERMINAL 



TERMINAL 



specifies how much of listing is 
transmitted to terminal. 



SMESSAGE/LMESSAGE enables you to specify concise 

or full message format. 



Figure 3.1. (Part 2 of 3) Compiler options arranged by function 
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OPTIONS LISTED BY FUNCTION PART 3 



OPTIONS TO SPECIFY STATEMENT NUMBERING SYSTEM USED 



NUMBER S GONUMBER 



STMT S GOSTMT 



OFFSET 



numbers statements according to 
line on which they start- 



numbers statements sequentially. 

specifies that a listing 
associating statement numbers 
with offsets will be generated 
Thus enabling you to identify 
statements from offsets given 
in execution time error 
messages. 



OPTIONS FOR USE WHEN DEBUGGING 

FLOW 

COUNT 



generate code that will result 
in a trace of executed 
statements being retained. 

generate code that will result 
in a count of the number of 
times each statement is executed 
being printed at the end of the 
program. 



OPTION TO IMPROVE COMPILATION/EXECUTION SPEED 

OPTIMIZE(TIME) 



NOOPTIMIZE 



reduce execution time at the 
expense of compilation. 

reduce compilation time at the 
expense of execution. 



OPTION TO ALLOW EXECUTION UNDER OS 

OSDECK* 



specifies that compiler will 
produce OS compatible code. 



OPTION FOR USE WHEN DEBUGGING THE COMPILER 



DUMP 



produces a dump if the compiler 
terminates abnormally. 



OPTION FOR USE ON IMPRECISE INTERRUPT: MACHINES 



IMPRECISE 



allows imprecise interrupts 
to be correctly handled. 



OPTIONS FOR SYSTEMS PROGRAMMING 



CONTROL ( 'password* ) allows access to deleted options 

for those who know password. 



* Options marked thus are ignored if used in the +PROCESS statement 

L 

Figure 3.1. (Part 3 of 3) Compiler options arranged by function 
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ALPHABETICAL LIST OF OPTIONS 



AGGREGATE | NOAGGREGATE 
AG | NAG 



The abbreviated form must be used in PLIOPT command. 

The AGGREGATE option specifies that the compiler is to produce 
an aggregate length table, giving the lengths of all arrays and 
major structures in the source program. 



ATTRIEUTES 1 NOATTRIBUTES 
AINA 



The abbreviated form must be used in PLIOPT command. 

The ATTRIBUTES option specifies that the compiler is to include 
in the compiler listing a table of source-program identifiers 
and their attributes. If both ATTRIBUTES and XREF apply, the 
two tables are combined. 



CHARSET (t 48 | 60] ] t EBCDIC J BCD ] ) 
CS([48|60]| [EBJB]) 

The CHARSET option specifies the character set and data code 
that you have used to create the source program. The compiler 
will accept source programs written in the 60-character set or 
the 48-character set, and in the Extended Binary Coded Decimal 
Interchange Code (EBCDIC) or Binary Coded Decimal (BCD). 

§.Q",..9£-fi§r,^haracter set: If the source program is written in 
the 60-character set, specify CHARSET (60); if it is written in 
the 48-character set, specify CHARSET (48). The language 
reference manual for this compiler lists both of these 
character sets. (The compiler will accept source programs 
written in either character set if CHARSET(48) is specified. 
However, if the reserved keywords, for example CAT or LE are 
used as identifiers in a program using the 60 character set, 
errors may occur if it is compiled with the CHARSET (48) 
option) . 

BCD or EBCDIC: If the source program is written in BCD, specify 
CHARSET (BCD); if it is written in EBCDIC, specify CHARSET 
(EBCDIC). The language reference manual for this compiler lists 
the EBCDIC representation of both the 48-character set and the 
60-character set. 

If two arguments (48 and ECD or 60 and EBCDIC) are specified, 
either argument may appear first. One or more blanks must 
separate the arguments. 

COMPILE j NCCOMPILE [ (W | E | S ) ] 
C|NC| [ (W|E|S)T 

The abbreviated form must be used in PLIOPT command for 
NOCOMPILE. 

The COMPILE option specifies that the compiler is to compile 
the source program unless an unrecoverable error was detected 
during preprocessing or syntax checking. The NCCOMPILE option 
without an argument causes processing to stop unconditionally 
after syntax checking. With an argument, continuation depends 
on the severity of errors detected after the syntax checking 
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phase as follows: 

NOCOMPILE(W) No compilation if a warning, error, 
severe error, or unrecoverable 
error is detected. 

NOCOMPILE (E) No compilation, if error, severe 
error, or unrecoverable error is 
detected. 

NOCOMPILE (S) No compilation if a severe error or 
unrecoverable error is detected. 



CONTROL ( * password " ) 



The CONTROL option specifies that any compiler 
options deleted for your installation are to te 
available for this compilation. You must still be 
specify the appropriate keywords to use the 
options. The CONTROL option must be specified with 
a password that is established for each 
installation; use of an incorrect password will 
cause processing to be terminated. 

"password* is a character string, not exceeding six characters 
in length. 



COUNT|NOCOUNT 
CT| NCT 



The COUNT option specifies that code will be generated to allow 
a count to be kept of the number of times each statement is 
executed in a particular run of a program to be generated at 
the end of the run. 

Unless overridden at execution time by the NOCCUNT option, it 
will result in a count of the number of times each statement in 
a program has been executed being printed on the PLIDUMP file 
cr, if there is none, on the SYSPRINl file, after the execution 
of the compiled program. 

The CODE generated for the COUNT option also allows a trace of 
the most recently executed statements to be retained if the 
FLOW option is specified at execution time. 

The COUNT option implies the GONUMBER option if the NUMBER 
option is in effect and the GOSTMT option if the STMT option is 
in effect. 



DECK | NODE CK 
D|ND 



The DECK option specifies that the compiler is to produce an 
object module in the form of 8 0-column card images and store it 
in the data set defined by the DD statement with the name 
SYSPUNCH. Columns 73-76 of each card contain a code to 
identify the object module; this code comprises the first four 
characters of the first label in the external procedure 
represented by the object module. Columns 77-80 contain a 4- 
digit decimal number: the first card is numbered 0001, the 
second 0002, and so on. 



DUMP | NODUMP 
DUINDU 
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Do not use in *PROCESS statement unless also used in the PLIOPT 
command 

The DUMP option specifies that the compiler is to produce a 
formatted dump of main storage if the compilation terminates 
abnormally (usually due to an I/O error or compiler error). 
This dump is written on the file associated with ddname 
SYSPRINT. Details of the suboptions of DUMP are given in the 
OS PL/I Optimizing Compiler Program Logic. 



ESD1N0ESD 



The ESD option specifies that the external symbol dictionary 
(ESD) is to be listed in the compiler listing. 



FLAG(I|W| E|S) 
F(I]W|E|S) 



The FLAG option specifies the minimum severity of error that 
requires a message to be listed in the compiler listing. The 
format of the FLAG option is: 

FLAG (I) List all messages. 

FLAG(W) List all except informatory 

messages. If you specify FLAG, 
FLAG(W) is assumed. 

FLAG (E) List all except warning and 
informatory messages. 

FLAG(S) List only severe error and 

unrecoverable error messages. 



FLOW(n m) j NOFLOW 



The FLOW COMPILER OPTION SPECIFIES THAT CODE WILL BE PRODUCED 
ENABLing the transfers of control most recently executred in a 
program to be listed when an ON statement with the SNAP option, 
or when a CALL PLIDUMP statement is executed. This enables you 
to follow the path through the most recently executed 
statements. The format of the FLOW option is: 

FLOW(n m) 

where "n w is the number of transfers of control that 
will be listed with associated statement 
numbers. 

where "m" is the number of transfers of control 

between procedures that will be listed with 
associated procedure names. 

n and m must be decimal integers and may not exceed 3276 8. If 
either value is zero, the associated listing will not be 
produced. 

The list will start with the earliest available information and 
continue to the point where the CALL PLIDUMP statement or the 
ON statement with the SNAP option was executed. 

The code generated for the FLOW compiler option allows the 
COUNT execution time option to be used if it is specified at 
execution time. 
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GONUMBER| NOGONUMBER 
GNl NGN 



The abbreviated forir, must be used in the PLIOPT command for 
NOGONUMBER. 

The GONUMBER options specifies that the compiler is to produce 
additional information that will allow line numbers from the 
source program to be included in execution-time messages. 
Alternatively, these line numbers can be derived by using the 
offset address, which is always included in execution-time 
messages, and the table produced by the OFFSET option. 

Use of the GONUMBER option implies that the NUMBER option will 
a PPly- See "Relationship of Statement Numbering Options" at 
the start of this chapter. 



GOSTMT | NOGOSTMT 
GS] NGS 



The GOSTMT option specifies that the compiler is to produce 
additional information that will allow statement numbers from 
the source program to be included in execution-time messages. 
Alternatively, these statement numbers can be derived by using 
the offset address, which is always included in execution-time 
messages, and the table produced by the OFFSET option. 

Use of the GOSTMT option implies that the STMT option will also 
apply- See "Relationship of Statement Numbering Options" at 
the start of this chapter. 



IMPRECISE | NOIMPRECISE 
IMPlNIMP 



The abbreviated form must be used in the PLIOPT command. 

The IMPRECISE option specifies that the compiler is to include 
extra text in the object module to localize imprecise 
interrupts when executing the program with an IBM System/360 
Model 91 or 195, or System 370 model 195. This extra text 
ensures that if interrupts occur, the correct cn-units will be 
entered. 



INCLUDE j NOINCLUDE 
INCjNINC 



The INCLUDE option specifies that SSINCLUDE statements are to be 
handled without the overhead of using the full preprocessor 
facilities. If preprocessor statements other than %INCLUDE are 
used in the program the MACRO option must be used. 

The INCLUDE option will be overridden if the MACRO option is 
also specified. 



INSOURCEj NOINSOURCE 
IS|NIS 



The abbreviated form must be used in the PLIOPT command for 
NOINSOURCE. 

The INSOURCE option specifies that the compiler is to include a 
listing of the source program (including preprocessor 
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statements) in the compiler listing. This option is applicable 
only when the preprocessor is used, therefore the MACRO option 
must also apply. 



LINECOUNT (n) 1 LINECOUNT (55) 
LC(n) 



The abbreviated form must be used in the PLIOPT coirirand. 

The LINECOUNT option specifies the number of lines to te 
included in each page of the compiler listing, including 
heading lines and blank lines. The format of the LINECOUNT 
option is: 

LINECOUNT (n) 

where "n" is the number of lines. It must be in the 
range 1 through 32767, but if you specify less 
than 1 , only the heading of the listing will be 
printed. 



LIST[ (m n)] ]NOLIST 



The LIST option specifies that the compiler is to include a 
listing of the object module (in a form similar to IBM 
System/360 assembler language instructions) in the compiler 
listing. 

m and n allow you to specify the range of statements for which 
the list will be produced. If m and n are omitted the complete 
program is included in the listing. 



LMESSAGE J SMESSAGE 
LMSG | SMSG 



The LMESSAGE and SMESSAGE options specify that the compiler is 
to produce messages in a long form (specify LMESSAGE) or in a 
short form (specify SMESSAGE). Short messages save printing 
time at the terminal. 



MACRO | NOMACRO 
MINM 



The MACRO option specifies that the source program is to be 
processed by the preprocessor. 



MAP I NCMAP 



The MAP option specifies that the compiler is to produce tables 
showing the organization of the static storage for the object 
module. These tables consist of a static internal storage map 
and the static external control sections. The MAP option is 
normally used with the LIST option. 

Use of the MAP option also results in the generation of a 
variables offset map which lists static internal and automatic 
variables with the offsets from their defining bases. This 
simplifies finding variables in a dump. 



MARGINI ( • c * ) | NOMARGIN I 
MK'c') 1NMI 
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The abbreviated form must be used in the PLIOPT command for 
NOMARGINI. 

The MARGINI option specifies that the compiler is to indicate 
the position of the margins by including in the listings of the 
PL/I program a specified character in the column preceding the 
left-hand margin, and in the column following the right-hand 
margin. Any text in the source input which precedes the left- 
hand margin will be shifted left one column, and any text that 
follows the right-hand margin will be shifted right one column. 
Thus the text outside the source margins can be easily 
detected. The MARGINI option applies to both the SOURCE and 
INSOURCE listings. 

The MARGINI option has the format: 

MARGIN I ( , c t ) 

where "c" is the character to be printed as the margin 
indicator. 



MARGINS(2,72 f l) (F-format records) 
MARGINS (10,100,0) (V- format records) 

MAR(m n [c] ) 

The MARGINS option specifies which part of each compiler input 
record contains PL/I statements, and the position of the ANS 
control character that formats the listing. The MARGINS option 
is used to override the default margin positions that are set 
up during compiler installation by the FMARGINS and VMARGINS 
options . 

The FMARGINS default applies to F-format records and the 
VMARGINS default applies to V- format or U-format records. Only 
one of these defaults is overridden by the MARGINS option. If 
the first input record to the compiler is F-format, the 
FMARGINS default is overridden. if the first input record to 
the compiler is a V- or U-format record the VMARGINS default is 
overridden by the MARGINS option. Default values are assumed 
if a record with a different type of format is encountered by 
the compiler. 

The format of the MARGINS options is: 

MARGINS 9m, n, c) 

where: 

ir is the column number of the leftmost column that will be 
scanned by the compiler, m must not exceed 100. 

n is the column number of the rightmost column that will be 
scanned by the compiler, n must not be less than m, nor 
greater than 100. 

c is the column of the ANS printer control character. It must 
not exceed 100 and it must be outside the values specified for 
ir and n. A value of for c indicates that no ANS control 
character is present. The control character applies only to 
listings on a line printer; it is ignored in conversational- 
mode listings at the terminal, only the following control can 
be used: 
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(blank) skip one line before printing. 

Skip two lines before printing. 
Skip three lines before printing. 

+ Skip no lines before printing. 

1 Start new page. 

Any other character is taken to be blank. If the value c is 
greater than the maximum length of a source statement record 
the compiler will not be able to recognize it; consequently the 
listing will not have the required format. 



MDECK | NOMDECK 
MD I NMD~ 



The MDECK option specifies that the preprocessor is to produce 
a copy of its output (see MACRO option) and write it to the 
file defined by the ddname SYSPUNCH. The MACRO option produces 
8U byte records; however, the last four bytes, which contain 
sequence numbers, are ignored for the output from MDECK option. 
Thus MDECK allows you to retain the output from the 
preprocessor as a deck of 80-column punched cards. 



NAME) ( *ob ject-module-name* ) 
N (* object -module-name* ) 

No default applies. NAME must be specified if required. 

The NAME option specifies that the TEXT file created by the 
compiler will be given the specified external name. This 
allows you to create more than one text file when doing batch 
compilation and also allows you to produce TEXT files suitable 
for inclusion in a text library (see section headed "Compiling 
the Program - the PLIOPT Command".) 

The name option has the format: 

NAME ( • object-module-name ' ) 

where "object-module-name" has from one through six 

characters, and begins with an alphabetic 
character. 



NEST 1 NONE ST 



The NEST option specifies that the listing resulting from the 
SOURCE option will indicate, for each statement, the begin- 
block level and the do-group level. 



NUMBER | NONUMBER 
NUMlNNUM 



The NUMBER option specifies that the numbers specified in the 
sequence fields in the source input records are to be used to 
derive the statement numbers used in the compiler listings. 

The position of the sequence field can be specified in the 
SEQUENCE option. Alternatively, the following default positions 
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are assumed: 

• Last 8 columns for fixed-length source input records. 

• First 8 columns for undefined-length or variable-length 
source input records. In this case, 8 is added to the 
values used in the MARGINS option. 

These defaults are the positions used for line numbers 
generated by CMS; thus it is not necessary to specify the 
SEQUENCE option, or change the MARGINS defaults when using the 
line numbers generated by CMS. Note that the preprocessor 
output has fixed-length records irrespective of the format of 
the primary input. Any sequence numbers in the primary input 
are repositioned in columns 73-80. 

The line number is calculated from the five right-hand 
characters of the sequence number (or the number specified, if 
less than five) . These characters are converted to decimal 
digits if necessary. Each time a line number is found which is 
not greater than the preceding one, 100000 is added to this and 
all following line numbers. 

If there is more than one statement on a line, a suffix is used 
to identify the actual statement in the messages. For example, 
the second statement beginning on the line 40 is numbered 40.2. 
The maximum value for this suffix is 31. Thus the thirty-first 
and subsequent statements on a line have the same number. 

The use of NONUMBER is equivalent to the use of STMT, and 
GONUMBER implies NUMBER see "Relationship of Statement 
Numbering Options" at the start of this chapter. 



OBJECT | NOOB JECT 
OBJ] NOB J 



The OBJECT option specifies that the compiler is to create an 
object module and store it on the TEXT file. 



OFFSET | NOOFFSET 
OFlNOF 

The OFFSET option specifies that the compiler is to print a 
table of statement numbers for each procedure with their offset 
addresses relative to the primary entry point of the procedure. 
This table can be used to identify a statement from an 
execution-time error message if the GONUMBER or GOSTMT option 
is not in effect. 

OPTIMIZE (TIME | 0) 2) | NOOPTIMI ZE 
OPT (TIME) | 2) JNOPT 

The abbreviated form must be used in the PLIOPT command for 
NOOPTIMIZE. 

The OPTIMIZE option specifies the type of optimization 
required: 

NOOPTIMIZE specifies fast compilation speed, but inhibits 
optimization for faster execution and reduced 
main storage requirements. 

OPTIMIZE (TIME) specifies that the compiler is to optimize the 
machine instructions generated to produce a very 
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efficient object program. A secondary effect of 
this type of optimization can be a reduction in 
the amount of main storage required for the 
object module. The use of OPTIMIZE (TIME) could 
result in a substantial increase in compile time 
over NOOPTIMIZE. 



OPTIMIZE (0) is the equivalent of NOOPTIMIZE. 

OPTIMIZE (2) is the equivalent of OPTIMIZE (TIME) . 

The language reference manual for this compiler includes a full 
discussion of optimization. OPTIMIZE will be accepted if 
spelled OPTIMISE. 



OPTIONS | NOOPTIONS 
OP | NOP 



The abbreviated form must be used in the PLIOPT command for 
NOOPTIONS. 

The OPTIONS option specifies that the compiler is to include in 
the compiler listing a list showing the compiler option used 
during this compilation. This list includes all those options 
applied by default, those specified in the PARM parameter of an 
EXEC statement, and those specified in a +PROCESS statement. 



CSDECK 
OSD 



This is a PLIOPT option and is ignored if used in the *PRCCESS 
statement. 

The OSDECK option specifies that the compiler will produce 
output that can be executed under the control of OS. If the 
OSDECK option is not used, the first record in the TEXT and 
SYSPUNCH files is a CMS loader control card specifying the 
execution time interface module as the entry point. This 
record results in an error of severity level 8 if it is passed 
to the OS linkage editor. 

There is no negative form, and OSDECK must be specified 
if it is required. 



PRI NT | DISK | NOPRI NT 
PRIjDl|NOPRI 

This is a PLIOPT option and is ignored if used in the *PROCESS 
statement. 

Directs the compiler listing file to the printer (PRINT) or to 
disk (DISK — this is the default). If NOPRINT is specified 
the file is not written. 

SEQUENCE (ir n) |NOSEQUENCE 
SEQ(m n) | NSEQ 

IBM-default: F-format records SEQUENCE (73 80) 

V- or U-format records SEQUENCE (1 8) 

i The SEQUENCE option defines the section of the input record 

| from which the compiler will take the sequence number. 

| (sequence numbers are used to calculate statement numbers if 
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the NUMBER option is in effect.) 

During compiler installation, two default values are set up. 
One value is for F- format records, the other is for V- or U- 
format records. The SEQUENCE option overrides only one of 
these values. The value overridden is the value that applies 
to the first record read by the compiler. If a second type of 
record is found the default sequence values will apply to this 
type of record. 



SEQUENCE (n m) 
where: 



ir specifies the column number of the leftmost digit of the 
sequence number. 

n specifies the column number of the rightmost digit of the 
sequence number 



size (yyyyyyyy I yyyyyK | max) 
sz (yyyyyyyy | yyyyyK | max) 



This option can be used to limit the amount of main storage 
used by the compiler. This is of value, for example, when 
dynamically invoking the compiler, to ensure that space is left 
for other purposes. The SIZE option can be expressed in three 
forms: 

SIZE (yyyyyyyy) specifies that the compiler should attempt 

to obtain YYYYYYYY bytes of main storage 
for compilation. Leading zeros are not 
required. 

SIZE (yyyyyK) specifies that the compiler should attempt 

to obtain YYYYYK bytes of main storage for 
compilation (1K=1024) . Leading zeros are 
not required. 

SIZE (MAX) obtain as much main storage as it can. 

The IBM default, and the most usual value to be used, is 
SIZE (MAX), which permits the compiler to use as much main 
storage in the partition or region as it can. 

When a limit is specified, the amount of main storage used by 
the compiler depends on how the operating system has been 
generated, and the method used for storage allocation. The 
compiler assumes that buffers, data management routines, and 
processing phases take up a fixed amount of main storage, but 
this amount can vary unknown to the compiler. 

Note: Under CMS, SIZE (MAX) should always be used unless it is 
essential to limit the space used. If a limit is set in the 
SIZE option, the value used will exceed that which is 
specified. This is because storage is handled by a 
CMS/compiler interface routine and not directly by the 
compiler. 

The value specified in the SIZE option cannot exceed the main 
storage available for the job step and cannot be changed after 
processing has begun. This means that in a batched compilation 
the value established when the compiler is invoked cannot be 
changed for later programs in the batch. Thus it is ignored if 
specified in a * PROCESS statement. 
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SOURCE | NOSOURCE 
SINS 



The SOURCE option specifies that the compiler is to include in 
the compiler listing a listing of the source program. The 
source program listed is either the original source input or, 
if the MACRO option applies, the output from the preprocessor. 



STMT I NOSTMT 



The STMT option specifies that statements in the source program 
are to fce counted, and that the resulting number is to be used 
to identify statements in the compiler listings. If NCSTMT is 
specified, NUMBER is implied. STMT is implied by NONUMBER or 
GOSTMT. (For further information see "Relationship of 
Statement Numbering Options" earlier in this chapter.) 



STORAGE j NOSTORAGE 
STG | NSTG 



The abbreviated form must be used in the PLIOPT command for 
NOSTORAGE. 

The STORAGE option specifies that the compiler is to include in 
the compiler listing a table giving the main storage 
requirements for the object module. 



SYNTAX | NOSYNTAX [ ( W j E | S ) 3 
SYN|NSYN[(W|E|S) ] 



The SYNTAX option specifies that the compiler is to continue 
into syntax checking after initialization (or after 
preprocessing if the MACRO option applies) unless an 
unrecoverable error is detected. The NOSYNTAX option without an 
argument causes processing to stop unconditionally after 
initialization (or preprocessing). With an argument, 
continuation depends on the severity of errors detected during 
preprocessing, as follows: 

NOSYNTAX (W) No syntax checking if a warning,, error, severe 
error, or unrecoverable error is detected. 

NOSYNTAX (E) No syntax checking if an error, severe error, or 
unrecoverable error is detected. 

NOSYNTAX (S) No syntax checking if a severe error or 
unrecoverable error is detected. 

If the SOURCE option applies, the compiler will generate a 
source listing even if syntax checking is not performed. 

The use of this option can prevent wasted runs when debugging a 
PL/I program that uses the preprocessor. 

TERMINAL [( opt- list) 3 | NOTERMINAL 
TERM[ (opt-list)3 |NTERM 

The abbreviation must be used in the PLIOPT command for 
NOTERMINAL. 

The TERMINAL option is applicable only in a conversational 
environment. It specifies that some or all of the compiler 
listing is to be printed at the terminal. If TERMINAL is 
specified without an options list, diagnostic and informatory 
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messages are printed at the terminal. You can add an argument, 
which takes the form of an option list, to specify other parts 
of the compiler listing that are to be printed at the terminal. 

The listing at the terminal is independent of that written on 
the LISTING file. However, if the ddname LISTING is associated 
with the terminal, only one copy of each listing requested will 
be printed, even if it is requested in the TERMINAL option and 
also as an independent option. The following option keywords, 
their negative forms, or their abbreviated forms, can be 
specified in the option list: 

AGGREGATE, ATTRIBUTES, ESD, INSOURCE, LIST, MAP, OPTIONS, 
SOURCE, STORAGE, and XREF. 

In the PLIOPT command, abbreviatons must be used for any option 
that exceeds eight characters in length. Values for the other 
options that relate to the listing (that is, FLAG, NUMBER, 
STMT, LINECOUNT, LMESSAGE/SMESSAGE, MARGINI, NEST, and NUMBER) 
will be the same as for the LISTING file. 



XREFINOXREF 
X|NX 



The XREF opt 
the compiler 
program, tog 
they are dec 
label refere 
For example, 
PROC1 is END 
will not app 



ion specifies that the compiler is to include in 

listing a list of all identifiers used in the PL/I 
ether with the numbers of the statements in which 
lared or referenced. (The only exception is that 
nces on END statements are not included, 
assume that statement number 20 in the procedure 
PROCl;. In this situation statement number 20 
ear in the cross reference listing for PROCl.) 



If both ATTRIBUTES and XREF apply, the two listings are 
combined into one table. 



60 



Chapter 4: Execution Time Options 



The PL/I Optimizing Compiler produces compiled code to which various 
execution time options may be passed. These options enable you to 
control the amount of storage used during execution, and to override the 
PL/I error handler's attempts to intercept program check interrupts and 
ABENDS. and, provided that either FLOW or COUNT HAS BEEN SPECIFIED as a 
compiler option, to specify that a count of the number of times each 
statement has been executed be generated or that a trace of the most 
recently executed statements be retained, or both. Execution time 
options are sometimes called program management parameters. 

A set of default execution time options are established during system 
generation. These can be overridden by options specified in a PL/I 
variable PLIXOPT, and these in turn can be overridden by options 
specified with the START command or with the filename when it is used as 
a command . 

To specify execution time options within a PL/I program, you must use 
the following declaration: 

DCL PLIXOPT CHAR(len) VAR INIT Cstrg') STATIC EXTERNAL; 

where "strg" is a list of options separated by blanks or commas, and 
"len" is a constant equal to or greater than the length of "strg". 

If more than one external procedure in a job declares PLIXOPT as STATIC 
EXTERNAL, the string in the first program passed to the loader will be 
taken as the list of options and the second and subsequent strings 
ignored. 

The execution time options can be specified with the START command or 
with the filename of a MODULE file when it is used as a command. If a 
parameter is also being passed to the main procedure, it must follow any 
execution time options and be preceded by the characters blank, oblique 
stroke, blank ( / ). Program management parameters must be separated 
from each other by blanks. 

A typical START command specifying execution time options (NCSPIE and 
REPORT) and a main procedure parameter (734) might be: 

start * ncspie report / 734 

List of Execution Time Options 

The following is a list of execution time options: 

COUNT 

specifies that a COUNT of the number of times each statement in 
the program was executed will be produced if either the COUNT 
or FLOW option was specified at as a compiler option. (If 
neither was specified as a compiler option, an error message is 
issued and the request for COUNT is ignored.) 

The count is transmitted to the PLIDUMP file when the program 
has completed execution, to highlight statements that have not 
been executed, a separate list of such statements is produced. 



NOCOUNT 



specifies that a count of the number of times each statement 
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has been executed will not be produced. NOCOUNT is used to 
prevent a program compiled with the COUNT option from producing 
count information. Even when NOCOUNT is specified, a 
considerable time and space overhead is incurred by a program 
compiled with the COUNT option. To get the best performance a 
debugged program must be recompiled without the 



| FLOW 
I 



specifies that a trace of the most recently executed statements 
will be retained and that this will be printed when an on-unit 
with the SNAP option is entered or when a call to PLIDUMP with 
the trace option is made. The option is only effective if 
either FLOW or COUNT was specified as a compiler option. (If 
neither was specified an error message is issued and the option 
is ignored.) 

The format of the FLOW option is FLOW [ (n m)3 where n specifies 
the number of branch-out/branch- in statement number pairs to be 
retained, and m specifies the number of changes of procedure or 
on-unit that are retained, n and m can have different values 
from those specified in the compiler FLOW option. If n and m 
are omitted both at compiler time and at execution time, 
default values of 25 for n and 10 for m are assumed. 

The trace is transmitted to SYSPRINT AND TAKES THE FORM: 



NOFLOW 



3 TO 8 IN TESTER 

12 TO 17 

22 TO 3 IN DRIVER 



201 
202 
203 



Meaning that a branch was made from statement three to 
statement 8 which is in the procedure named TESTER, than ran 
sequentially to statement 12 when a branch to 17 was made then 
ran sequentially to 22 where a branch to statement 3 which is 
in DRIVER was made. 



specifies that a trace of the most recently executed statements 
will not be retained. It is used to override the FLOW compiler 
option, 

Even when NOFLOW is specified, considerable time and space 
overheads are incurred by programs compiled with the FLOW 
option. when a program has been debugged it should be 
recompiled without the FLOW COMPIler option to achieve maximum 
efficiency. 



isasize (yyyyylyyyyyK) 



specifies the amount of main storage initially acquired for 
automatic, controlled, and based variables, and compiled code 
workspace. 

Allocation of PL/I dynamic storage on the entry of blocks and 
for the allocation of controlled and based variables is carried 
out as far as possible within this area. When there is 
insufficient room, storage is acquired from the system and a 
time overhead is involved. However if a large value is 
specified in ISASIZE, storage may be wasted, and there may be 
insufficient storage for I/O buffers and transient library 
routines. 

If ISASIZE is not specified, a default value is applied. This 
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REPORT 



value is half of the storage remaining in the region after 
storage for the load module has been allocated rounded up to 
the nearest 2K bytes. 

The REPORT execution time option can be used to help work out 
the optimum ISASIZE. 

specifies that a table showing the use of storage by the 
program will be transmitted to the PLIDUMP file at the end of 
the execution of the program. Under CMS the PLIDUMP file is 
assigned to the printer by default. 



The REPORT option should be 
value to specify in ISASIZE 
table "Amount of PL/I Stora 
execution with the minimum 
as the ISASIZE. However, 1 
controlled or based variabl 
program, the programmer may 
these allocated by the syst 
smaller ISASIZE value may 
smaller region, although ex 



used to help calculate the best 
The value given in the REPORT 
ge Used" would give the fastest 
total waste of storage if specified 
f a number of PL/I blocks or 
es are little used during the 

prefer to have storage for some of 
em. In this situation, specifying a 
enable the program to run in a 
ecution time may increase. 



Note; The use of the REPORT parameter considerably slows 
execution. It is intended as an aid for program development, 
not for regular use. 



NOREPORT specifies that a report table will not be generated, 
default. 



It is the 



STAE specifies that when an ABEND occurs, an attempt will be made to 
call the PL/I error handler and raise the PL/I ERROR condition. 
It is the default. 

NOSTAE specifies that on program initialization, a STAE macro 

instruction is not to be issued, and consequently the PL/I 
error handler will not be called to attempt to raise the ERROR 
condition when an ABEND occurs. 

SPIE specifies that when a program interrupt occurs, an attempt will 
be made to call the PL/I error handler to raise the ERROR 
condition. It is the default. 

NOSPIE specifies that on program initialization, a SPIE macro 

instruction is not to be issued, and consequently the PL/I 
error handler will not be called to raise the ERROR condition 
when a program check interrupt occurs. 
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source program on 25 
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immediate 13 

IPL 12 

LOAD 27 

LOGIN 10 

LOGOUT 33 

MACLIB 20,24 
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compiler 43 
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length restriction 24 

list of defaults 4 3 
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CONTROL option 5 
conventions, PL/I 

conversational I/O 37 

DISPLAY and REPLY 40 
conversational I/O 37,4 

assigning SYSIN to terminal 31 

automatic padding with blanks 40 

ENDFILE 40 

ending file 4 

GET DATA 4 

GET EDIT 40 

GET SKIP 40 

line continuation character 39 

PRINT file formatting 37 

simplified punctuation 40 

SKIP for input 4 

with DISPLAY and REPLY 4 
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COUNT option 

compile time 50 
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DECK option 50 
deleting 
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files (see ERASE command) 
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logical character delete characte 

incorrectly typed lines (see logical 
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output disk 23 

parent disk 2 3 

source disk 23 

source program not on 25 

transferring source to 25 
DISK option 23,57 
DISPLAY statement 4 
DMSIBM, interface module 31,32 
DUMP option 51 



EBCDIC 49 

EDIT command 15 

edit mode 18 

editor, CMS 15 

ENDFILE marker 40 

ending input on file 4 

ENDPAGE in conversational I/O 37 

entering data 12 

ERASE command 33 

escape character 13 

ESD option 51 

EVENT option 35 

EXEC, profile 14 

execution 

compiled program 27 

file compiled under OS 32 

file compiled with OSDECK option 32 

MODULE file 27 

TEXT file 27 

under OS 25 



fast %INCLUDE compiler option 52 
FETCH statement 35 
FILE command 15,18 
filename 15 

as command 27 

naming PLIOPT files 15 
files 
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COPY 2 

creating 22 

deleting 34 
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LISTING 22 

MODULE 27 

PL/I and CMS defaults 31 

PLI 18 

PLIOPT 18 
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GONUMBER option 52 
GOSTMT option 52 

halting execution, HX command 13 
halting typing, HT command 13 
HT (halt typing) command 13 
HX (halt execution) command 13 
hyphens at end of lines 39 

identifier, virtual machine 10 
immediate commands 13 
IMPRECISE option 52 
INCLUDE compiler option 52 
INCLUDE statements 20,24 



66 



included text 24 
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INPUT mode 18 

INSOURCE option 53 

interface module, DMSIBM 31,32 

IPL command 12 

ISASIZE option 62 



keyboard, locking 12 



line deletion 13 

line editing characters 13 

LINECOUNT option 53 

LIST option 53 

LISTING file 22 

listing options, choosing 23 

LMESSAGE option 53 

LOAD command 27 

locking of keyboard 12 

logical character delete character 

logical line 39 

logical line delete character 13 

logical line end character 13 

LOGIN command 10 

LOGOUT command 3 3 

LOGOUT HOLD command 34 
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character string constants 19 

input 19 



MACLIB 24 
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MACRO option 52,53 
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MARGINS 15 
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NOFLOW option 51 

execution time 62 
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NOMAP option 53 
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NOMDECK option 55 

non-CMS source programs 25 
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NOSPIE option 63 

NOSTAE option 63 

NOSTMT option 59 

NOSTORAGE option 5 9 
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NOTERMINAL option 60 
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OBJECT option 56 
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Optimizing Compiler (see compiler) 

options 5 4 
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PLIOPT 44 
compiler 44,54 
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CONTROL option 50 
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using 31 
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program management 31 

restrictions 31 
parent disk 23 

parenthesis as line editing character 13 
password 
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ASCII data sets 35 
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PLICKPT 3 5 
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PLIOPT command 4 3 

example and discussion 21 
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syntax 43 
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PLISTART as name of TEXT file 26 
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PLIXOPT 61 
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pound sign (#) as line editing 

character 13 
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%INCLUDE without using preprocessor 52 
primary prompt 3 8 
PRINT file 37 

conversational formatting 
conventions 37 

overriding formatting conventions 37 
PRINT option 23,, 57 
printer control character 54 
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profile EXEC 14 
prompting, conversational I/O 38 



QUIT command 18 

quotes as line editing character 
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page breaks at terminal 37 
PAGE option and format item 37 
PAGELENGTH 37 
PAGESIZE 37 



records 

VBS-format 35 
VS-format 35 

RELEASE statement 35 
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REPLY option 40 
REPORT option 63 
restrictions 

PL/I,, (see PL/ 1 restrictions) 
RT (resume typing) command 13 
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syntax conventions, summary 41 
SYNTAX option 59 
SYSIN, assigning to terminal 31 
SYSPRINT, assigning to terminal 
system requirements for CMS 9 
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SAVE command 18 

secondary input text 20, 24 

creating 20 
secondary input to compiler 52 
secondary prompt 38 
SEQUENCE option 58 
sixty character set 4 9 
SIZE option 58 
SKIP on input 40 
SKIP option and format item 37 
SMESSAGE option 53 
sort facility 35 
source code 54 

position in record 54 
source disk 23 
SOURCE option 59 
SPIE option 63 
STAE option 63 
star PROCESS statements 19 
START command 27 
STMT option 59 
stopping 13 

execution 13 

typing (terminal printout) 13 
STORAGE option 5 9 
storage requirements for CMS 9 
stream I/O 

DATA dir€»cted conventions 40 

EDIT directed 4 

LIST directed conventions 40 
subcommands (see commands and subcommands) 
switched line connection, retaining 34 



tabs 15,37 
tape 25,3 5 

BACKWARDS attribute 35 

source program on 25 
tasking 3 5 

teleprocessing files 35 
TERMINAL command 13 
TERMINAL option 23,60 
terminal session 

ending 33 

starting 10 
terminal, listings transmitted to 
TEXT file 27 

creating 22 

executing 27 
text libraries 2 6 
transmitting data 12 
TXTLIB command, troubles with 26 
typing errors, correcting 13 



upper case 15,19 



VBS-format records 35 
VS- format records 3 5 



workfiles, compiler 24 
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48-character set 49 



60-character set 49 
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Action 
by 



Terminal Printout 



Notes and comments 



Explanation of sample terminal session 
The terminal session has been planned to 
show various features of CMS. The program 
is a simple conversational program that 
responds with one of two well known 
quotations when the correct author is 
specified. It has been written to show the 
conversational I/O and parameter 
conventions of PL/I under CMS. 

The first column in the figure shows 
whether the terminal print out is entered 
by the user or is tranmsitted by the 
system. The second column shows the 
terminal printout. Where an action from 
the user would not result in words 
appearing on the terminal printout, the 
action to be taken is placed in 
parentheses. For example "(you switch on 
terminal)" in line 1. The third column 
contains notes and comments. The fourth 
column gives the page of the book where a 
fuller explanation of the point being 
illustrated can be found. Throughout the 
example certain blank lines have been 
omitted to allow the complete session to 
appear on one page. 



user 

system 

user 

system 

user 

system 

user 
system 
user 
system 

user 

system 

user 



user 

system 

user 

system 

user 

system 



system 

user 

system 

user 

system 

user 



sytem 



user 
system 

user 
system 

user 



opto 



(you switch on terminal) 

d'x38z irvy; vm370 online 

(you press attention key 

login robin 

ENTER PASSWORD: 

(you enter password) 

LOGMSG 08:09:08 GMT MONDA^O 

LOGON AT 08:25:34 GMT MONDA 

ipl cms 

CMS 1.0 PLC 5 

edit skylark pliopt 

NEW FILE: 

EDIT: 

input 

INPUT: 

skylark: proc (charparm) 
del (charparm, quotation, 
string=translate(charparn 
on endfile (sysin) goto 

start: 

if string=*percy bysshe 

'hail to thee blythe 

esiaalse if string='will 

'a skylark wounded on th 

else quotation='no known 

put skip edit (quotation, 

(a,skip(5)) ; 
get edit(string) (a(80)) ; 

finis: display ( 'thank you 

end skylark; 

(you press carriage return 

EDIT: 

file 

R; T=0.35/0.91 08.26.32 

pliopt skylark (xref a 

PL/I OPTIMIZING COMPILER V3 

OPTIONS SPECIFIED 

XREF, A, TERM 



tc unlock terminal) 



5/13/73 
05/13/73 



NO MESSAGES PRODUCED FOR Th 



ns (main) ; 

^ring) char (100) var; 
« « t ) . 

finis; 

elley' then quota tion= 
pirit* ; 

blake* then quotation= 
wing/a cherubim doth cea 
uotation' ; 
Inter new name or endfile' 



3m 



Message when you switch on. 

Enter 'login' followed by name of virtual machine 

Printing of password normally suppressed 

Log message from system 

Invoke CMS 

Message shows CMS version in use 

Edit mode to enter program as a CMS PLIOPT file 

Shows that you have no PLIOPT file called skylark 

Shows you are in edit mode 

Tell system further input will be part of file 

Shows that you are in input sufcmode 

PL/I program entered in either capitals or lower 

case letters. Use columns 1 through 71 

CMS interface removes blanks from main procedure 

parameter. Program uses commas and translates. 



a a deletes two previous incorrect characters 
se to sing' , 



oto start; 

your company*); 



fr 



ey) 



Rl.2 TIME 08.34.51 DATE 



Skip (5) is interpreted as skip (3) at terminal 

Sent to terminal (console of virtual machine) 

Ends input submode 

Message confirms you are back in edit mode 
Stores input as PLIOPT file skylark 
Ready message, CMS ready for further commands 
Compile command, options preceded by ( 
13 MAY 1973 

TERM specified by CMS Interface module 



S COMPILATION 



COMPILE TIME 0.02 MINS SP^L FILE RECORDS SIZE 4051 

R; T=2.74/4.41 08.38.37 

global txtlib plilib 

R; T=0.03/0.04 08.41.49 

load skylark 

R;T=1.11/1.85 08.50.06 

start * / percy, bysshe, skflley 



EXECUTION BEGINS. . . 

HAIL TO THEE BLYTHE SPIRIT 



ENTER NEW NAME OR ENDFILE 

/* 

THANK YOU FOR YOUR COMPANY 

R;T=1.52/2.46 08.45.06 

logout 

CONNECT=00.33. 59 VIRTCPU=OK): 09.11 TOTCPU=000: 16. 55 

LOGOFF AT 08:59:33 GMT MCJTDAY MAY 13 1973 

(you switch off terminal) 



Make the PL/I library avialable 

resolve addresses in PL/ I program 

Note parmeter must be divided into 8 character 
tokens. Blanks are removed. Note also blanks 
after * and / 
Message from CMS 
Output from program 



Prompt shows input required from terminal 

Endfile marker 

Message from DISPLAY statement 

Command ends terminal session 

Logoff message 



Page for 
more data 



Page 10 
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Figure F.l A sample terminal sessim 
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